Agent API Readiness Checklist

Use this checklist to evaluate whether an API is practical for autonomous agents, workflow automation, and MCP-style tool integrations. A good agent-ready API is not only documented; it is safe, discoverable, debuggable, and forgiving under partial failure.

Updated: June 13, 2026 · Review note: AI-assisted draft; requires human review by Cly before any public distribution. This page is an evaluation aid, not a compliance certification, security audit, or guarantee that autonomous execution is safe.

Fast decision rule

An API is agent-ready only when a bounded automation token can discover the operation, validate inputs, preview or safely retry writes, observe the result, and stop cleanly when risk increases. If any step depends on hidden UI state, tribal knowledge, or irreversible side effects, keep a human in the loop.

1. Authentication and permissions

• Supports scoped tokens rather than all-powerful account keys.
• Can create short-lived or revocable credentials for automation.
• Separates read, write, admin, billing, and destructive permissions.
• Has clear rate limits and error messages for auth failures.
• Allows read-only mode for exploration and dry-run workflows.

2. Machine-readable documentation

• OpenAPI, JSON Schema, MCP server, SDK, or equivalent structured interface exists.
• Every operation has stable names, required fields, schemas, and response examples.
• Examples include real request/response bodies, not only prose.
• Error codes are documented with recovery guidance.
• Pagination, filtering, sorting, and idempotency behavior are explicit.

3. Safe write operations

• Dangerous actions have preview, validate, or dry-run modes.
• Write operations are idempotent where possible, especially POST-style creates.
• Bulk operations return per-item success/failure details.
• Rollback, undo, or compensating actions are documented.
• Writes can be constrained by explicit resource IDs, limits, and confirmation tokens.

4. Observability for agents

• Every mutation returns stable IDs and enough state to verify success.
• Audit logs can identify automation-created changes by token, app, or actor.
• Webhook/event support exists for long-running workflows.
• Failure responses include actionable messages rather than generic 500s.
• Rate-limit responses include remaining quota, reset timing, or retry guidance.

5. Copyable scoring rubric

Copy this rubric into an issue, review doc, or spreadsheet. Score each dimension from 0–5. Do not average away a critical 0: a single missing safety control can make autonomous operation unsafe even when the total looks acceptable.

Agent API readiness rubric v1
API / product:
Reviewer:
Date:
Use case being evaluated:

1. Permission boundaries (0-5): ___
0 = one broad account key or shared admin credential only
1 = token exists but scopes are broad, unclear, or hard to revoke
2 = basic read/write separation, limited automation controls
3 = scoped tokens, revocation, and readable auth errors
4 = short-lived or app-specific tokens with least-privilege defaults
5 = granular scopes, actor attribution, rotation, sandbox, and read-only exploration

2. Machine-readable contract (0-5): ___
0 = undocumented or UI-only workflow
1 = prose docs only; examples incomplete or stale
2 = partial endpoint docs; schemas missing for errors or edge cases
3 = OpenAPI/JSON Schema/SDK/MCP-like contract for core operations
4 = contract includes examples, pagination, filtering, rate limits, and error recovery
5 = versioned contract with testable schemas, changelog, and deprecation policy

3. Safe write design (0-5): ___
0 = irreversible writes with no validation, idempotency, or undo path
1 = writes work only if the caller guesses hidden defaults correctly
2 = limited validation; retries may duplicate or corrupt records
3 = idempotency keys or natural idempotency for common writes
4 = dry-run/preview, per-item bulk results, and documented rollback paths
5 = bounded writes with explicit resource IDs, confirmation tokens, quotas, and safe retry semantics

4. Agent observability (0-5): ___
0 = success/failure cannot be verified programmatically
1 = generic errors; no stable IDs or useful status fields
2 = basic IDs returned but weak failure details or no audit trail
3 = stable IDs, status fields, and actionable errors
4 = audit logs, request IDs, rate-limit headers, and webhook/event support
5 = full traceability from token to action, deterministic read-back, and machine-readable recovery hints

5. Operational guardrails (0-5): ___
0 = no sandbox, limits, alerts, or human approval checkpoints
1 = manual conventions only; no enforceable controls
2 = coarse limits or alerts exist outside the API
3 = sandbox/test mode plus configurable quotas or approval steps
4 = per-token limits, anomaly alerts, and human escalation paths
5 = policy-enforced budgets, no-go triggers, staged rollout, and automatic stop conditions

Total: ___ / 25
Interpretation:
0-9   = Human-only. Do not give this API to autonomous agents.
10-15 = Assisted only. Human approval and manual verification required for writes.
16-20 = Limited autonomy. Use narrow scopes, dry-runs, monitoring, and rollback plans.
21-25 = Strong candidate. Still start with low-risk tasks and staged rollout.

6. Endpoint teardown: weak write vs agent-ready write

This example shows why a superficially simple write endpoint may still be unsafe for autonomous agents.

Before: weak write endpoint

POST /v1/customers/update
Authorization: Bearer sk_live_shared_admin
Content-Type: application/json

{
  "customer": "Acme",
  "plan": "pro",
  "notes": "upgrade now"
}

200 OK
{
  "ok": true
}

• Ambiguous target: customer is a name, not a stable ID; duplicates or fuzzy matches can update the wrong record.
• Overbroad auth: shared admin credential gives the agent more power than the task needs.
• No idempotency: retrying after a timeout may create duplicate side effects.
• No preview: the caller cannot validate the change before execution.
• No verification: {"ok": true} does not expose changed fields, actor, audit ID, or rollback path.

After: more agent-ready endpoint

POST /v1/customers/cus_123/plan-change-requests
Authorization: Bearer app_token_plan_writer
Idempotency-Key: 7b4c4b1d-1c47-4f62-a0f2-example
Content-Type: application/json

{
  "target_plan": "pro",
  "effective_at": "2026-07-01T00:00:00Z",
  "mode": "preview",
  "client_request_id": "agent-run-456",
  "reason": "approved internal migration test"
}

200 OK
{
  "request_id": "pcr_789",
  "mode": "preview",
  "status": "requires_confirmation",
  "customer_id": "cus_123",
  "current_plan": "team",
  "target_plan": "pro",
  "estimated_invoice_delta": 1200,
  "required_scope": "customers.plan_write",
  "confirm_endpoint": "/v1/plan-change-requests/pcr_789/confirm",
  "expires_at": "2026-06-13T15:00:00Z",
  "rollback_endpoint": "/v1/plan-change-requests/pcr_789/rollback",
  "audit_event_id": "evt_abc"
}

• Stable resource: path uses cus_123, not a free-text customer name.
• Narrow permission: token is limited to plan changes, not account administration.
• Safe retry: idempotency key and client request ID let the agent retry without double execution.
• Preview-first: the endpoint returns a proposed change and requires a separate confirmation step.
• Observable: response includes status, audit event, confirmation path, expiry, and rollback path.

7. NO-GO for autonomous agents

Do not allow autonomous agents to execute writes against an API when any of the following are true:

• No scoped token: the only usable credential is a human admin key, shared password, or all-access token.
• No stable target IDs: write operations depend on names, search results, screen order, or other ambiguous selectors.
• No dry-run or validation for high-impact changes: billing, deletion, access control, data export, notifications, or irreversible state changes execute immediately.
• No idempotency for retries: network failure or timeout can duplicate charges, messages, records, or destructive operations.
• No machine-readable errors: the agent cannot distinguish invalid input, permission failure, rate limit, transient outage, or policy block.
• No audit trail: the organization cannot later identify which automation token changed what and why.
• No rollback or compensating path: the only recovery route is manual support intervention or database repair.
• No human approval path for sensitive actions: the API cannot pause for review before external communication, spending, customer-data movement, or permission changes.

Sources and observations

This checklist is based on observed failure modes in agent tool integrations: overbroad credentials, missing schemas, unsafe retries, ambiguous writes, poor rate-limit signals, and unverifiable side effects. Useful public references:

• OpenAPI Specification 3.1 for machine-readable API contracts.
• Stripe API idempotent requests as a concrete retry-safety pattern.
• GitHub REST API rate limits for quota and reset-signal expectations.
• OWASP API Security Top 10 2023 for common API risk categories.

Internal links: all VFrontier tools, MCP readiness scorecard, and static site monetization roadmap.