Preparing your APIs for an AI agent

To let an AI support agent act in your systems, give it a small set of purpose-built endpoints instead of your internal API: separate read and write endpoints, a dedicated least-privilege credential, an idempotency key on every write, and a confirmation step before anything irreversible. Responses should be small and stable, with explicit fields and a human-readable reason on every failure, and every call should be fast, rate-limited, testable in a sandbox and written to an audit log. The agent is a new kind of client: it calls your APIs mid-conversation, on behalf of one customer, with inputs taken from natural language. Design for those three facts.

The shape of the integration

Keep a layer between the agent and your core systems. That layer owns the policy (which customer, which action, which limits), the credential and the logging, so the agent never needs broad access.

Start from tasks, not from your API

List the customer tasks you want the agent to complete, then derive the endpoints. This keeps the surface small and easy to justify in a security review.

Task	Reads	Writes	Reversible?	Limits
Where is my order?	Order status, tracking	None	Not applicable	Own orders only
Change delivery address	Order status	Update address	Yes, until shipped	Before dispatch only
Replace a lost card	Account status, active cards	Freeze card, order card	Freeze yes, order no	Fraud checks pass
Refund an order	Order, refund eligibility	Issue refund	No	Up to your auto-approve limit

Build one endpoint per task step rather than exposing a generic “update customer” call. A narrow endpoint is easier to secure, test and explain.

Separate reads from writes

Reads give the agent context: plan, account state, recent orders. They should be safe to call often, side-effect free, and use GET. Writes change state: cancel, refund, update. They should be few, explicit, and use POST or PUT. Keep them on separate credentials or scopes so a lookup integration can never move money.

Scoping and least privilege

Give the agent its own service identity. Never reuse an employee account or an admin key. You want to revoke it, rate-limit it and audit it on its own.
Scope per endpoint. A credential for order lookups should not reach the refunds endpoint.
Bind every call to the customer in the conversation. Enforce on the server that the record requested belongs to the verified customer. Don’t rely on the agent to pass the right ID: inputs come from conversation text, and a customer can type someone else’s email.
Enforce limits on the server. Refund caps, allowed plan changes and eligibility rules belong in your API, so they hold even if the agent’s configuration is wrong.
Use separate credentials per environment (sandbox, staging, production).

Authentication patterns

Pattern	When it fits	Watch for
API key in a header	Server-to-server calls with a small number of endpoints	Store it in a secrets manager, rotate on a schedule, never share it over email or chat
OAuth client credentials	You already run an identity provider for service clients	Token lifetime and refresh; keep scopes narrow
Mutual TLS or an IP allowlist	Extra assurance on top of a key or token	Not a replacement for per-request auth

Whichever you choose, validate the credential on every request and reject anything else with 401 Unauthorized.

Idempotency keys for writes

Networks time out and calls get retried. Without protection, a retry after a slow response can issue a second refund or a second replacement card. An idempotency key fixes this: the caller sends a unique key with each write, and your server stores the result for that key. A repeated request with the same key returns the stored result instead of acting again.

POST /refunds HTTP/1.1
Content-Type: application/json
Idempotency-Key: conv_8812_refund_order_5521

{ "order_id": "5521", "amount_cents": 2400 }

Derive the key from something stable, such as the conversation and the intent, so that the same request in the same conversation always maps to the same key. Keep keys long enough to cover your retry window, and return the same response body on a replay.

Confirmation before irreversible actions

Classify every write as reversible (address change before dispatch), reversible at a cost (cancellation with a fee) or irreversible (refund, data deletion, transfer). For the last two:

Read before you write. Check eligibility and current state with a read endpoint first.
Confirm with the customer using a plain summary of exactly what will happen: “I’ll cancel your Pro plan today. Your final charge is on June 15. Should I go ahead?”
Re-check preconditions on the server at write time, since state can change during the conversation.
Hand off above a threshold. Above your limit, the endpoint should refuse with a clear reason, and the agent should route the case to a person.

A stricter variant: a preview endpoint returns what would happen plus a token, and the commit endpoint accepts only that token, so the confirmed action and the executed action are the same.

Response shape

The fields you return become what the agent can reason about and say. Keep responses small, flat and predictable.

Return only what the task needs. Every extra field is data the agent might repeat to the customer.
Use explicit fields. "account_closed": true is clearer than inferring state from a status code buried in a nested object.
Keep names and types stable. The same field, same case style, same type, in every response. Return null rather than omitting a field.
Prefer low-cardinality enums for status fields, with any display label in a separate field.
Include a human-readable reason, written so it could be shown to a customer.

{
  "success": false,
  "error_code": "OUTSIDE_REFUND_WINDOW",
  "message": "This order was delivered 45 days ago. Refunds are available for 30 days.",
  "eligible_for_store_credit": true
}

Error design

Separate business outcomes from protocol failures. “Not eligible for a refund” is a valid answer: return 200 OK with success: false, a stable error_code and a message. Reserve 4xx and 5xx for bad input, missing auth and server errors. The code lets the agent branch (offer store credit, hand off); the message lets it explain. Never return stack traces in error bodies.

Situation	Status	Body
Action completed	`200`	`success: true`, plus result fields such as a confirmation ID
Business rule refused it	`200`	`success: false`, `error_code`, customer-readable `message`
Missing or malformed input	`400`	Which field is wrong
Bad credential	`401`	Generic message
Record not found for this customer	`404`	`error_code` such as `USER_NOT_FOUND`
Rate limit reached	`429`	A `Retry-After` header
Unexpected failure	`500`	Generic message; details go in your logs

Latency budgets

The customer is waiting while the agent calls you, often across several calls in one turn. Set a budget per endpoint, keep reads faster than writes, and time out rather than hang. Avoid endpoints that fan out to many downstream services. For work that genuinely takes long (a document check, a bank transfer), accept the request quickly, return a reference and status, and let the agent tell the customer when to expect the result.

Rate limits

Agent traffic follows conversation volume, so it spikes during outages and campaigns. Give the agent’s credential its own limit so it can’t starve other clients, return 429 with Retry-After, and share the limit with whoever configures the agent.

Sandbox and test environments

Provide a sandbox that implements the same contract as production, with test customers that cover your real cases: active, closed, high-risk, several cards, no orders. Add a way to force failures (timeouts, 500s, business refusals) so you can test how the agent recovers. Never point a new write integration at production until it has passed a representative set of test conversations in the sandbox.

Audit logging

Log every agent call so any action can be traced back to a conversation.

Field	Why
Timestamp and endpoint	What happened, when
Credential or service identity	Which client made the call
Conversation or interaction ID	Links the call to the transcript
Customer ID	Whose record was read or changed
Idempotency key	Ties retries to the original request
Outcome and error code	What the customer was told

Redact secrets and sensitive values such as full card numbers, and keep logs for as long as your own retention policy requires.

Readiness checklist

Common mistakes

Exposing the internal admin API with one broad key.
Trusting the customer ID the agent passes without checking it on the server.
Retries without idempotency, which turns a timeout into a duplicate refund.
Business refusals as 500s, so the agent can’t tell “not eligible” from “broken”.
Nested, changing response shapes that break the agent’s field mappings after a release.
Testing only the happy path in the sandbox.

Doing this in Fini

In Fini (usefini.com), your endpoints plug in like this:

The contract Fini expects: HTTPS only, JSON in and out, an x-api-key header on every request, flat responses with stable fields, and a target of under two seconds for reads and under five seconds for writes. Write responses return success and message, plus error_code on failure. See the API contract, which also lists what to send your Fini contact, including rate limits and expected latency.
Reads and writes: read endpoints become Attributes, which run on every message; write endpoints become Actions, which run only when a Tool node in a published Rulebook rule invokes them. Test an Action with sample inputs using the Play button before saving.
Regression tests and live calls: Test Suite uses recorded or mock Action responses and never calls your endpoints, so it checks the agent’s decisions (which Action, when, and how it handles a Success or Failure response) but not your API itself. Check the live endpoints end to end against your sandbox, then in a controlled pilot.
Idempotency on MCP tools: if a write tool on a connected MCP server declares an idempotency_key input, Fini generates and injects one per conversation and intent. See MCP Connections.
Keys for calling Fini: if your systems also call Fini’s public APIs, use workspace keys from Deploy → API Keys with only the read or write scope they need. See API Keys.
A worked example: the card replacement walkthrough chains a lookup attribute, two write Actions, a Form for the shipping address and a Reply Behavior fraud gate, built in a sandbox first.

API contract

Endpoint requirements, sample requests and responses, and the handoff checklist.

Actions

Typed API calls the agent runs from a Rulebook Tool node.

Card replacement walkthrough

Two chained write Actions with a fraud gate, end to end.

Designing an escalation policy

Which conversations, including high-value actions, must reach a person.

Use cases

Walkthroughs

Industry setup

How-tos

Playbooks

Preparing your APIs for an AI agent

The shape of the integration

Start from tasks, not from your API

Separate reads from writes

Scoping and least privilege

Authentication patterns

Idempotency keys for writes

Confirmation before irreversible actions

Response shape

Error design

Latency budgets

Rate limits

Sandbox and test environments

Audit logging

Readiness checklist

Common mistakes

Doing this in Fini

API contract

Actions

Card replacement walkthrough

Designing an escalation policy

​The shape of the integration

​Start from tasks, not from your API

​Separate reads from writes

​Scoping and least privilege

​Authentication patterns

​Idempotency keys for writes

​Confirmation before irreversible actions

​Response shape

​Error design

​Latency budgets

​Rate limits

​Sandbox and test environments

​Audit logging

​Readiness checklist

​Common mistakes

​Doing this in Fini

​Related

API contract

Actions

Card replacement walkthrough

Designing an escalation policy

The shape of the integration

Start from tasks, not from your API

Separate reads from writes

Scoping and least privilege

Authentication patterns

Idempotency keys for writes

Confirmation before irreversible actions

Response shape

Error design

Latency budgets

Rate limits

Sandbox and test environments

Audit logging

Readiness checklist

Common mistakes

Doing this in Fini

Related