Acme Payments API
v2026-01-01Acme Payments has a valid OpenAPI spec with strong coverage for read endpoints, but mutation endpoints are missing idempotency guidance, several error responses are undocumented, and destructive billing operations are not clearly labeled for agent safety.
Where the points went
A prioritized plan, ready for tickets
Ordered by impact on agent and tool-call reliability, with a suggested owner and effort estimate.
7 findings with evidence & fixes
Each finding points to an exact JSON pointer in the spec, with impact, recommendation, and a copy-ready fix.
DELETE /users/{id} is destructive but has no safety guidance
This operation appears to delete a user, but the spec does not describe whether the action is reversible, requires confirmation, supports soft delete, or should be withheld from autonomous agents.
An AI agent could trigger an irreversible action without enough context or approval boundaries.
Document the side effect, required scope, confirmation requirement, audit behavior, and whether the delete is soft or hard.
/paths/~1users~1{id}/deletedelete:
operationId: delete_user
summary: Permanently delete a user
x-agent-safety:
risk: irreversible
requiresApproval: true
reversible: false
responses:
"204": { description: User deleted }Missing 2xx response schema for POST /customers
This operation returns a successful response without a defined schema. SDK generators and AI agents need a machine-readable output contract, not prose.
Agents may not know which fields are returned after creating a customer, making follow-up steps unreliable.
Add a 201 response that references the Customer schema and include at least one JSON example.
/paths/~1customers/post/responses/201responses:
"201":
description: Customer created
content:
application/json:
schema:
$ref: "#/components/schemas/Customer"
examples:
created:
value: { id: "cus_123", email: "jane@acme.com" }POST /payments has no idempotency guidance
The payment creation endpoint does not document an idempotency key or duplicate-protection behavior.
Agents retry after timeouts. Without an idempotency key, a retry can double-charge a customer.
Accept an `Idempotency-Key` header and document how duplicate requests are de-duplicated server-side.
/paths/~1payments/postparameters:
- in: header
name: Idempotency-Key
required: true
schema: { type: string, format: uuid }
description: Safely retry without creating a duplicate payment.No documented error responses on POST /refunds
Only a 200 response is documented. There are no typed 4xx/5xx responses describing validation or failure modes.
Agents cannot recover from failure because they don't know what errors to expect.
Document 400/402/409 responses with a shared Error schema, a request id, and a machine-readable error code.
/paths/~1refunds/post/responses"402":
description: Refund exceeds available balance
content:
application/json:
schema: { $ref: "#/components/schemas/Error" }GET /invoices does not document pagination
This list endpoint returns an array with no documented cursor, page parameter, or total-count behavior.
Agents cannot reliably traverse all results and may silently process only the first page.
Document cursor-based pagination with `limit` and `starting_after`, and return a `has_more` flag.
/paths/~1invoices/getparameters:
- { in: query, name: limit, schema: { type: integer, default: 20 } }
- { in: query, name: starting_after, schema: { type: string } }operationId "doAction" is not MCP-friendly
The operationId does not convey intent. Tool generators and agents rely on verb_noun names to choose the right tool.
An agent is more likely to select the wrong tool or misuse this endpoint.
Rename to an explicit `verb_resource` operationId such as `update_billing_settings`.
/paths/~1billing~1doAction/post/operationIdpost:
operationId: update_billing_settings
summary: Update an account's billing settingsRate limits are not documented
No global or per-endpoint rate limit information is present in the spec or docs.
Agents call APIs in tight loops and unintentionally exceed limits, causing failures.
Document the rate limit window, the `429` response, and the `Retry-After` header behavior.
"429":
description: Too many requests
headers:
Retry-After: { schema: { type: integer } }See your API as agent tools — before you build them
VeriSpec grades whether each operation can become a clean, safe MCP tool: clear names, complete input schemas, predictable responses, and approval boundaries for dangerous actions.
{
name: "create_customer",
description:
"Create a new customer record. Requires customer.write scope. " +
"Do not use for duplicate detection; call search_customers first.",
inputSchema: {
type: "object",
required: ["email", "name"],
properties: {
email: { type: "string", format: "email",
description: "Customer email. Must be unique." },
name: { type: "string", description: "Full customer name." }
}
},
safety: { risk: "low_risk_write", requiresApproval: false,
scopes: ["customer.write"] }
}list_invoicesRead-only autosearch_customersRead-only autocreate_customerLow-risk write autorefund_paymentIrreversible approvaldelete_userIrreversible approvalDestructive tools like refund_payment and delete_user are flagged to require human approval — so agents can plan safely.
Audit your API before AI agents do.
Run a free readiness scan in minutes. Get a score, the exact gaps, and a fix plan your team can ship.