# SICHER KI discovery API

Public, read-only discovery for agents. No account or API key is required. The specification is at [OpenAPI](https://sicher-ki.de/openapi.json).

## Endpoints

- `GET /.well-known/ard.json`: public resources in `entries`.
- `GET /.well-known/agents-index.json`: browser actions and input schemas in `actions`.
- `GET /.well-known/agent-skills/index.json`: usage instructions and digests in `skills`.

These endpoints also support HEAD. OPTIONS supports browser preflight for GET/HEAD and the API-Version header without consuming the read quota. Other methods return HTTP 405 with `Allow: GET, HEAD, OPTIONS`. Public discovery responses, including errors, allow cross-origin reads and expose API-Version, RateLimit-Policy, RateLimit, Retry-After, Link and Allow. Project contact and subscription forms require email confirmation; job applications deliver directly with explicit applicant permission and privacy acknowledgement; see [access requirements](https://sicher-ki.de/auth.md).

## Versioning and deprecation

Send `API-Version: 1`. Omitting the header remains pinned to version 1. Responses return the selected version in `API-Version` and include `Vary: API-Version`. Unsupported versions return HTTP 400 with `code: unsupported_api_version`.

Compatible additions keep the same major version. Existing fields, types and meanings remain stable; clients should ignore unknown additional fields. Breaking changes receive a new major version.

Deprecation will be announced in this document and through the `Deprecation` header using the structured date format from [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745). A planned removal will be signalled through the `Sunset` header from [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594), with at least 90 days' notice. Sunset will not precede deprecation. Version 1 is not deprecated, so neither date header is currently sent. The response's `Link: ...; rel="deprecation"` points here.

```sh
curl -H 'API-Version: 1' https://sicher-ki.de/.well-known/agents-index.json
```

## Errors

Discovery errors use `application/problem+json` following [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Responses include `type`, `title`, `status`, `detail`, `code`, `message` and `hint`. OpenAPI describes HTTP 400, 404, 405, 429, 500 and 503 with a shared typed schema.

```sh
curl -i -H 'API-Version: 2' https://sicher-ki.de/.well-known/agents-index.json
```

```json
{"type":"about:blank","title":"Bad Request","status":400,"detail":"Bad Request","code":"unsupported_api_version","message":"Bad Request","hint":"Set API-Version: 1 or omit the header to use version 1."}
```

## Rate limits

The three discovery endpoints share 120 requests per 60 seconds per client IP and Cloudflare location. Every non-preflight request counts, including HEAD and invalid requests. Enforcement is approximate and not globally synchronized. People behind the same IP share the quota. Browser form limits remain separate. Job applications allow five requests per minute per IP and Cloudflare location; a 429 includes Retry-After: 60.

Responses from these endpoints advertise:

```http
RateLimit-Policy: "discovery";q=120;w=60
```

HTTP 429 also includes:

```http
RateLimit: "discovery";r=0
Retry-After: 60
```

Wait at least the Retry-After delay before retrying a read. Cloudflare supplies no remaining counter, so successful responses do not report one. These structured fields follow [draft-ietf-httpapi-ratelimit-headers-11](https://www.ietf.org/archive/id/draft-ietf-httpapi-ratelimit-headers-11.html), which is an IETF draft, not an RFC.