Skip to main content
The abadge API is a JSON REST API served under the /v1 prefix. Every operation — organizations, profiles, items, agents, permissions, secret access, and audit — is a /v1 endpoint authenticated with a bearer token.

Authentication

Operator sessions, personal API keys, and agent keypair sessions.

Errors

The standard error envelope and every error code.

Rate limiting

Per-principal limits and recommended client behavior.

Pagination

Cursor pagination on the list endpoints that support it.

​
Base URLs

The OpenAPI 3.1 spec is served at /v1/openapi.json. The reference pages in this section are generated from that spec, so the documentation and the live API cannot drift apart.

​
Conventions

​
application/json
Request and response bodies are JSON.
​
string
Appear in curly braces, e.g. /items/{itemId}.
​
header
Every response includes an X-Request-Id header. Set your own and the server echoes it back — include it when reporting issues.
​
envelope
Every non-2xx response is a { code, message, hint, meta } envelope. Validation errors add an issues[] array. See Errors.

​
Organization scoping

Most endpoints are scoped to an organization. The server resolves the caller’s org in this order:
1

Header

The X-Abadge-Org-Id header, if present.
2

Sole membership

The single org the caller belongs to, when unambiguous.
3

Bound credential

The org embedded in an agent session or personal API key.
If a user belongs to multiple orgs and omits X-Abadge-Org-Id, the request fails with 400 and code: "ORG_HEADER_REQUIRED". The error’s meta.availableOrgIds lists the user’s orgs.

​
A first request

​
Surfaces

Human authentication lives at /api/auth/* and is not part of /v1. See Human authentication. Agents can self-register an unclaimed account through the agentic registration flow.

​
Clients

You can call /v1 with any HTTP client. For TypeScript projects, the official SDK wraps the API with typed methods, automatic auth headers, and — for agents — keypair session management.