Best use: paste this into an API design doc or pull request checklist. For each section, write down the concrete endpoint, field, status code, schema, or operational control that satisfies it.
Before the agent acts
Inspectable
Discovery and schemas
- Published OpenAPI/JSON Schema or equivalent machine-readable contract.
- Examples include realistic successful calls, validation failures, permission failures, and rate-limit responses.
- Endpoints exist to inspect current state before mutation, not just mutate and hope.
- Required scopes, roles, quotas, and destructive side effects are visible in docs and errors.
Bounded
Scoped authority
- Tokens can be limited by workspace, resource, operation, environment, budget, and expiry time.
- Dangerous operations support approval gates or separate elevated scopes.
- Read-only, dry-run, and preview modes are available for planning steps.
- Every credential can be revoked without disrupting unrelated users or systems.
When the agent acts
Scriptable
Stable operation surface
- All important workflows are callable through documented endpoints, not hidden UI flows.
- Write operations accept idempotency keys or equivalent duplicate-protection controls.
- Long-running work returns a durable job ID immediately.
- Pagination, filtering, sorting, and search are deterministic enough for repeatable automation.
Verifiable
Receipts by default
- Every mutation returns an ID, URL, diff, version, audit event, or other durable receipt.
- Status endpoints expose structured states such as
queued,running,succeeded,failed, andcancelled. - Responses distinguish accepted work from completed work.
- The agent can re-fetch the result later and cite evidence back to a human.
After something goes wrong
Recoverable
Failure and rollback
- Error responses are structured with stable codes, human-readable messages, and recommended next actions.
- Timeouts do not leave unknown state: agents can query status by idempotency key, job ID, or resource version.
- Retries are safe or explicitly marked unsafe.
- Rollback, cancel, restore, or human-takeover paths exist for consequential workflows.
Composable
Fits wider workflows
- Webhooks, events, logs, or export endpoints let other systems react to outcomes.
- Inputs and outputs use stable IDs and URLs that can move across repos, tickets, docs, inboxes, and schedulers.
- Audit trails identify actor, scope, request ID, source, timestamp, and changed resources.
- Rate limits and quotas are exposed in headers or machine-readable metadata.
Fast scoring rule
Ready for agent workflows
Most checklist items are satisfied with concrete endpoints, schemas, scopes, and receipts.
Most checklist items are satisfied with concrete endpoints, schemas, scopes, and receipts.
Useful but fragile
Agents can call the API, but humans still need to interpret state, approve broad access, or recover failures.
Agents can call the API, but humans still need to interpret state, approve broad access, or recover failures.
Not agent-first yet
The API mainly exposes raw actions without safe discovery, bounded authority, verification, or recovery.
The API mainly exposes raw actions without safe discovery, bounded authority, verification, or recovery.
Highest-leverage fix
Add the missing receipt, status, dry-run, scoped token, or idempotency feature that removes the biggest human supervision burden.
Add the missing receipt, status, dry-run, scoped token, or idempotency feature that removes the biggest human supervision burden.
Next: score the API with the full scorecard, then turn the weakest section into an engineering ticket.