---
name: "api_connector_builder"
description: "Wrap any REST API into an agent-usable tool: pick the auth pattern, map schemas to tool arguments, add pagination, retries, and structured error handling, then test the connector. Use when an agent needs to call a third-party or internal REST API reliably."
---

# API Connector Builder

## Purpose

Turn an unfamiliar REST API into a tool an agent can call without babysitting. The connector attaches auth correctly, pages long lists safely, retries transient failures, returns structured errors the model can branch on, and trims responses to what the model actually needs. All of that happens outside the model's view: the model sees clean tool functions, not HTTP plumbing.

## Workflow

1. **Recon the API (15 minutes).** Read the docs and record: auth scheme, whether an OpenAPI document exists (try `/openapi.json`, `/swagger.json`, or the docs page), rate limits, pagination style, and error format. Note anything weird now, not after you ship.
2. **Generate before hand-writing.** If an OpenAPI document exists, generate the client or tool schemas from it. See `references/openapi_tool_generation.md`. Hand-writing a client that a generator could produce is wasted effort and a bug farm.
3. **Auth.** Pick the pattern from `references/auth_patterns.md`. Load secrets from env or a vault, never hardcode them. Fail fast with a clear message when the credential is missing. Start from `bin/connector_template.py` and set `AuthConfig` for the provider.
4. **Schema mapping.** One tool per operation the agent needs, not one per endpoint. Name arguments for the task, not the API's internal field names. Trim every response with `shape` so the model gets a small, stable payload. Never pass raw API JSON through.
5. **Pagination.** Wrap list calls in `paginate()`. Cap pages per tool call (default 5 pages) and return a continuation token so the agent can ask for more. See `references/pagination_strategies.md`.
6. **Retries and errors.** Retry 429, 408, 5xx, and timeouts with exponential backoff plus jitter; honor `Retry-After`. Never retry 400/401/403/404: return a structured `{error, code, message, hint}` dict instead. The template does this already. See `references/retry_error_policy.md`.
7. **Mutations.** The template attaches an idempotency key to every POST/PUT/PATCH/DELETE automatically. Keep it: an agent will retry, and a retry must not create a duplicate.
8. **Test before shipping.** Follow `references/testing_checklist.md`: one read-only call against the real API, one paged list, one error path, one mutation in the provider's sandbox or dry-run mode if offered. Only ship what you verified live.

## Output Contract

A connector module that exposes tool functions which:

- take plain task-shaped arguments (not API-shaped ones),
- attach auth automatically and fail clearly when it is missing,
- page long lists with caps and continuation tokens,
- retry transient failures with backoff and jitter,
- return trimmed JSON or a structured error dict, never a stack trace,
- document each function with a one-line description and argument meanings.

Plus the decisions that shaped it: auth scheme, pagination style, retry policy, and the field shapes, written in comments or a short README so the next person is not guessing.

## Operating Rules

1. One connector, one base URL. Split providers into separate modules.
2. Never log, print, or echo credentials. The template redacts auth headers; keep that behavior.
3. Never invent status codes, rate limits, or field names. Verify from docs or the live API.
4. Every call gets a timeout (default 30s). No call without one.
5. Destructive actions get a second look: dry-run or sandbox first when the API offers it; confirm deliberate intent before a real delete or charge.
6. If the API changes out from under you (new required field, moved endpoint), fix the connector in one place: the mapping layer, not the tool functions.