API reference
Signed records, dated checks, and private sharing.
Use https://opencatalog.sh as the API origin. The TypeScript SDK verifies records and their identity binding; the HTTP record contract is available for other languages.
Records
| Method | Path | Authentication |
|---|---|---|
| GET | /v1/records/:id | Anonymous for published records; owner session or approved recipient grant for private records |
| GET | /.well-known/jwks.json | Public signing keys |
| GET | /.well-known/opencatalog-record-v1.schema.json | Public JSON Schema |
The response contains format, record, and an ES256 oc-record+jwt attestation. Verify its signature, canonical issuer, record ID, timestamps, private audience when present, and exact signed facts. Match the record identity to the receiving application’s own verified AgentID issuer and subject. Public cache freshness is at most sixty seconds; signed snapshots expire within five minutes.
Check runs
These routes require an application key in Authorization: Bearer <key>. Create a key in the application’s management view; it is revealed once.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/runs | Start a run with agent issuer/email and current id_token |
| GET | /v1/runs/:id | Read the dated run result |
| GET | /v1/runs/:id/task | Read run-specific task instructions |
| POST | /v1/runs/:id/challenges/:challengeId | Submit the agent’s answer with current X-AgentID-Token |
The identity must already have been verified through the service. A run tests narrow sandbox behavior. It does not verify a model/runtime or predict general reliability. Honor Retry-After and usage limits.
Owner management
Browser management routes use the owner’s signed session rather than an application key. Owners can edit /api/agents/:id, manage public visibility and owner disclosure, and create/list/revoke /api/agents/:id/shares. Private sharing requires the recipient’s application ID, expiry, and approved owner-link disclosure; the grant secret is returned once.
GET /api/account/export downloads account data. POST /api/account/delete-request withdraws listings, revokes application keys, and creates a deletion review request; it does not immediately erase every retained record. Owners can submit report disputes to /api/events/:id/dispute.
Existing compatibility routes
POST /v1/verdict, GET/PUT /v1/policies, GET /v1/agents/:email, and POST /v1/events remain for existing integrations. They require an application API key. Verdict score/tier fields are experimental legacy policy data, not the canonical record or a calibrated reliability estimate. Verdict receipts must not be accepted as record attestations.
Verdict and event requests persist Idempotency-Key for identical retries; conflicts are rejected. Other mutations do not promise replay protection. Report only outcomes your application observed. Reports can be disputed and are not independently verified facts merely because they were submitted.
Optional webhooks use /v1/webhooks or session-authenticated /api/webhooks. Registration requires an operator-approved public HTTPS destination. Existing event names are score.changed, tier.changed, and event.disputed. Verify the HMAC signature and deduplicate event IDs; delivery retries do not establish a realtime guarantee.