# Author HTTP

> Walk through authoring a kind:http DRIVER.md — wraps a third-party HTTP API (OpenAI / Stripe / Replicate / GitHub / Anthropic / etc.) as a conformant driver implementing one or more abstract TOOL contracts.

- Skill: `agentproto/author-http` (Agent Skill)
- Install (CLI): `npx skillmds@latest add agentproto/author-http`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agentproto/author-http/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: agentproto (https://skillmd.com/u/agentproto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/agentproto/author-http

---


# Author an HTTP driver (AIP-31)

Use when wrapping a third-party HTTP API as a conformant driver for
an AIP-14 TOOL contract. The skill produces a frontmatter-only
DRIVER.md when `body_template` + `response_extract` cover the
dispatch shape, OR a DRIVER.md + driver.ts when conditional
request shaping is needed.

## Process

1. **Identity**: pick `id` ending in `-http`, set `name`,
   `description`, `version`, `kind: http`, `base_url`.
2. **Auth**: pick the auth pattern.
   - `bearer-header` → `default_headers.Authorization: "Bearer ${secrets.X}"`,
     `auth.state.env: [X]`, `expiry.detect: "http_status:401"`.
   - `key-query` → no `default_headers`, per-tool `query_template.key:
     "${secrets.X}"`.
   - `oauth` → declare `auth.login.url`, `auth.refresh`,
     `requires_callback_url: true`. Refresh logic in `driver.ts`.
   - `custom` → write the entry's `login` / `refresh` / `parseResponse`.
3. **Per-tool dispatch**: for each TOOL ref, author `metadata.http`:
   - `endpoint` (relative to base_url)
   - `method` (default POST)
   - `body_template` for JSON request body; OR `query_template` for
     GET-style; OR omit and pass `args.input` verbatim
   - `response_extract` (JSONPath-lite) when the contract output is
     nested in the response body
   - `cost_override.cost_units_per_call` in millicents
4. **Sandbox + region + policy**:
   - `network.egress: [<api-host>]`
   - `region` (US, EU, global)
   - `policy_tags` (third-party-llm, third-party-api, gdpr-compliant)
5. **Health check** (recommended): `health_check.method: http,
   http: { method: GET, url: "<status-or-models-endpoint>", expect_status: 200 }, every: "PT5M"`.
6. **Validate** against `HTTP.schema.json` AND `DRIVER.schema.json`.
7. **Wire**: `loadProvider(...)` in the host; the resolver picks per
   call.

## Common mistakes

- **Hardcoded secrets in `default_headers`** — always use
  `${secrets.X}` substitution; never literal values.
- **Wildcard `network.egress`** — be specific to the API's host(s).
- **Missing `idempotency_key_header`** when the tool mutates external
  state — risks double-charges on retry.
- **Body templating for conditional fields** — when fields depend on
  input presence, use `driver.ts buildRequest()` instead of
  `body_template`.
- **TLS skip** — never. Hosts MUST validate certificates.