# Darlington public API operational policy

This policy applies to the public HTTP API at `https://www.darlington.dev`.
The current stable contract version is `2026-08-01`.

## One-request onboarding

No signup, API key, approval, trial, SDK, CLI or sandbox is required. Start with
one read-only production request:

```sh
curl -H 'API-Version: 2026-08-01' https://www.darlington.dev/api/profile
```

There is no separate test environment because public read operations expose
the same deliberately public portfolio data in production. `POST /api/contact`
sends a real message and should only be used after human confirmation.

## Versioning and deprecation

- Send `API-Version: 2026-08-01` to pin the current contract. Omitting it uses
  the current stable version.
- Additive fields may appear within a stable version. Breaking changes receive
  a new `API-Version` value.
- Version `2026-08-01` is active, is not deprecated and has no sunset date.
- A future deprecation will be announced at least 90 days before shutdown.
- Deprecated responses will carry the RFC 9745 `Deprecation` header. A planned
  shutdown will also carry the RFC 8594 `Sunset` header and migration links.
- Active responses link to this policy with `rel="deprecation"`. The policy
  link does not mean the current version is deprecated.

## Rate limits and retries

The application does not currently enforce a fixed request quota, so it does
not emit fabricated `RateLimit` or `RateLimit-Policy` values and does not
generate application-level `429 Too Many Requests` responses. Clients should
honour `Cache-Control`, avoid unnecessary polling and use exponential backoff
for transient failures. If an enforceable quota is introduced, responses will
publish its real `RateLimit` fields and `429` responses will include
`Retry-After`.

For `POST /api/contact`, send an `Idempotency-Key` when retrying. Reusing the
same key and payload within the provider's 24-hour window avoids sending a
duplicate email.

## Synchronous operations

Every public operation completes synchronously. There are no long-running jobs,
job identifiers or status endpoints to poll. If a long-running operation is
introduced, it will use `202 Accepted`, a `Location` header and a documented
status resource before clients are expected to use it.

## Client tooling

The small Darlington portfolio API has no official SDK or CLI. Use ordinary
HTTPS from any language, the OpenAPI specification, or the public MCP server.

Cortex is a separate open-source product created by Michael Darlington. Its
published npm, PyPI, Rust and Go clients and npm MCP bridge connect to Cortex;
they are not clients for the darlington.dev portfolio API. Canonical Cortex
package links are listed at `https://www.darlington.dev/developers#cortex-sdks`.

## References

- Developer resources: `https://www.darlington.dev/developers`
- OpenAPI: `https://www.darlington.dev/openapi.json`
- Authentication boundary: `https://www.darlington.dev/auth.md`
- MCP server: `https://www.darlington.dev/api/mcp`
- Access questions: `mailto:access@darlington.dev`