API overview

The Pore HTTP API lives at https://api.pore.dev. Every endpoint is versioned under /v1/ and speaks JSON.

Authentication

Authorization: Bearer <api-key>

API keys are tenant-scoped and carry a scope mask (check:read, grant:write, admin). Keys are created in the console or via POST /v1/keys with the admin scope.

Request identifiers

Every response includes X-Pore-Request-Id. Include it when opening a support ticket or correlating logs.

Rate limits

• Per-tenant rate limits keyed to plan.
• Headers: X-Pore-RateLimit-Limit, X-Pore-RateLimit-Remaining, X-Pore-RateLimit-Reset.
• On limit exceeded: 429 Too Many Requests with Retry-After.

OpenAPI schema

The machine-readable schema lives at /openapi.json. The human-readable reference on the following pages is hand-authored against the same schema; file an issue if you find a discrepancy. JUS-20 will wire auto-generation once apps/api emits the schema.

Versioning

• Path prefix /v1/ is reserved for the current major.
• Additive changes (new endpoints, new optional fields) are never breaking.
• Breaking changes increment the path prefix and ship with a deprecation window.

Errors

All error responses follow RFC 7807:

{
  "type": "https://pore.dev/errors/invalid-subject",
  "title": "Invalid subject identifier",
  "status": 400,
  "detail": "Subject must be of form 'namespace:external_id'",
  "instance": "req_01HXYZ..."
}

The type field is a stable identifier — match on it rather than on the detail string.