# geo.new agent API

POST `/api/v1/audits` with `Content-Type: application/json` and `{"url":"https://example.com"}`.
Keep the returned `geo_session` cookie and follow the response's `markdown_url` with that cookie.
Optional POST `/api/v1/session` establishes a session before a retry-sensitive creation request.
Supply a unique printable 16–128 character `Idempotency-Key`; retries with the same cookie, key and body bind to the original successful result for 24 hours. Changed bodies return 409.

Explicit Markdown reads return 202 while running, 200 when terminal (including failed reports). Read the report status and section coverage, not only the HTTP code. A snapshot requested through `GET /api/v1/audits/{id}` returns 200 at every available revision and supports `Accept: text/markdown`. GET/HEAD do not start work. Markdown contains deterministic findings plus any saved, labeled AI interpretations. It never triggers a new model call.

## Limits

All callers share 1,000 audit starts per rolling five minutes and 10,000 per hour. Anonymous limits: 5 starts/session/hour, 10/IP/hour, and one fresh run of an exact URL per five minutes. Cache/in-flight reuse consumes request limits, not audit admission limits. General requests: 180/session/minute and 600/IP/minute. Session issuance: 10/IP/hour. Keys with higher personal allowances are planned; they will still share global admission ceilings.

## Errors

Failures are JSON: `{"error":{"code":"…","message":"…","retryable":true,"request_id":"…","retry_after_seconds":10}}`.
Respect the `Retry-After` header. 429 means a rate bucket is full; 503 can mean temporary capacity or infrastructure trouble. 404 conceals whether a report is missing, expired, revoked or owned by another session. A lost initial cookie cannot recover a private report; establish a session first when exact retry binding matters.

Reports are private, expire after seven days, and use no-store/noindex headers. Sharing is an explicit browser action that creates a revocable bearer link to one immutable snapshot. Never include sensitive URLs in an audit. API tokens are not currently supported.

[OpenAPI contract](/openapi.json)

Dynamic Markdown responses include `X-Audit-Revision` and `X-Audit-Status` for the exact saved revision in the response body. Connection and loading observations distinguish direct fetch from browser lab timings; missing events remain unknown. Markdown reads do not create audits or model calls.