# Agentic API Experience

> Canonical: https://auxfirst.com/agentic-experience-center/agentic-api-experience.html
> License: CC BY 4.0 · auxfirst agency 2026

> Pillar 01 of the Agentic Experience Center · For app developers, platform teams, and infrastructure leads

The API surface designed for the **agent first**. AX — the new DX. Where the agent meets your software, designed for the agent's reasoning loop, not the developer's stack trace.

## What it is

The discipline of designing the API layer underneath an agent so the agent can:

- **Discover** what's possible — the tool surface is legible
- **Decide** safely — every action declares its consequences
- **Act** within bounds — permissions and policies are encoded, not documented
- **Recover** from failure — errors point to the next valid move
- **Explain** what happened — every action emits an auditable trace

Where AUX (Agentic User Experience) governs how humans and agents collaborate at the product surface, **AX governs how agents and software systems negotiate underneath it**.

## The shift, in one line

> API-first asks: *"Can a developer integrate this?"* Agent-first asks: *"Can an agent use this without creating chaos?"*

These are not the same question. And the products that answer the second one well will be the platforms of the next decade.

## API-first vs agent-first

| API-first design | Agent-first API design |
|---|---|
| Optimised for human developers | Optimised for agents *and* developers |
| Docs explain usage | Schemas encode intent and constraints |
| Errors help debugging | Errors help recovery and replanning |
| Auth protects systems | Permissions shape safe autonomy |
| Endpoints expose resources | Tools expose actions with consequences |
| Success means integration works | Success means the agent acts correctly |

## The six principles

### P1 · Design actions, not endpoints
Agents think in tasks. Developers think in resources. Expose an action layer above your REST primitives — `enrich_contact_profile`, `draft_follow_up_email`, `summarize_deal_risk`, `request_human_approval` — that maps business intent to system capability. The endpoints stay; the agent never has to assemble them.

### P2 · Make consequences explicit
Every action should declare what it reads, what it writes, who or what is affected, whether it is reversible, whether confirmation is required, and what the safe fallback is. If the agent cannot answer those six questions from the schema alone, the schema is incomplete.

### P3 · Separate read, suggest, and execute
The same business operation, three modes:
- `read_customer_data` — observe
- `suggest_account_update` — propose with rationale
- `execute_account_update` — act, with audit trail

The API-layer expression of the Control vs Autonomy map. Trust can be promoted and demoted per operation without redeploying.

### P4 · Build for recovery, not just success
The error surface is not a debugging tool — it is the **replanning surface**.

Bad:
```json
{ "error": "Invalid request" }
```

Agent-first:
```json
{
  "error": "missing_required_context",
  "missing_fields": ["company_id", "approval_reason"],
  "safe_next_steps": ["lookup_company_by_domain", "ask_user_for_approval_reason"],
  "retryable": true,
  "human_escalation": false
}
```

Same condition. Completely different downstream behaviour.

### P5 · Make capabilities discoverable
Each tool descriptor should encode purpose, allowed use cases, **disallowed use cases**, required context, examples, side effects, and escalation rules. The structural reason MCP matters: it is the first widely-adopted convention for describing capabilities in a way agents can reason about. It is a schema for trust, not just plumbing.

### P6 · Design trust into the API
An agent-first API is not a flat capability surface. It is a **topology of trust boundaries** — encoded in the schema, not in the docs. For every action, make four answers unambiguous:

- Can the agent read this?
- Can it write this?
- Can it act autonomously, or does it need confirmation?
- Who approves, what is logged, what can be undone?

The Functional/Contextual/Judgment/Advocacy trust ladder pulled down into structure.

## Why APIs built for humans break agents

Six recurring failure patterns:

1. **Ambiguous endpoint names.** Humans infer nuance. Agents overgeneralise. `update_contact` will be called for things that should never touch a contact record.
2. **Schemas that describe data, not intent.** A field called `status` is not enough.
3. **No asymmetry between read and write.** Reading is low-risk. Writing, sending, deleting, charging, publishing need visible trust boundaries.
4. **Errors that help debugging, not recovery.** `400 Bad Request` is useless to an agent that needs to replan.
5. **No escalation path.** APIs rarely tell agents *when not to proceed*.
6. **Documentation written for humans only.** Agents need machine-readable capability descriptions: purpose, allowed/disallowed use cases, side effects, escalation rules.

## Worked example — CRM API

**Before** (raw REST):
```
GET   /contacts/{id}
PATCH /contacts/{id}
POST  /tasks
POST  /emails
GET   /deals
```

**After** (action layer above the same primitives):
```
analyze_lead_fit
summarize_contact_history
recommend_next_best_action
draft_sales_followup
request_rep_approval
send_approved_followup
log_followup_outcome
```

Each action carries its consequence schema:
- `draft_sales_followup` — reversible, autonomous
- `send_approved_followup` — irreversible, requires approval from a named human role
- `recommend_next_best_action` — read-only, returns its reasoning trace

The traditional API is still there underneath. **The agent never touches it directly.**

## The ten-point checklist

For every API or tool surface you expose to an agent:

- Is the action name unambiguous and intent-shaped?
- Is the purpose clear from the schema alone, without external docs?
- Are side effects, reversibility, and downstream impact explicit?
- Are read, suggest, and execute modes separated where it matters?
- Is confirmation required — and named — for consequential actions?
- Are errors actionable, with safe next steps and retry semantics?
- Are capabilities discoverable in a machine-readable form (MCP or equivalent)?
- Does each tool include disallowed use cases, not just allowed ones?
- Is there a human escalation path with a defined approver role?
- Is there an audit trail the agent can reference *and* explain?

If you can't tick every box, the surface is half-designed.

## Engagement format

**Blueprint Sprint** — three weeks to map your current API surface, identify the action layer above it, define consequence schemas, and produce an implementation-ready agent experience specification.

**Advisory Retainer** — ongoing support as your agent-facing API evolves, autonomy levels shift, and new tools come online.

## Status

The practice page launches as the first engagement closes. The foundational essay is live now: https://auxfirst.com/news/agent-first-api-design.html

Engagement door is open: https://auxfirst.com/index.html#contact

## Related

- [Agent-First API Design — The New DX](https://auxfirst.com/news/agent-first-api-design.html) — the foundational essay
- [The Two-Layer Stack — AUX above Microsoft AGT](https://auxfirst.com/news/two-layer-stack-agt-vs-aux.html)
- [MCP for Advertising](https://auxfirst.com/ad-industry/mcp-for-advertising.html) — what changes for an agency stack
- [TrustKit on GitHub](https://github.com/auxfirst/trustkit) — schemas for agent specs, memory policies, tool catalogues