API / Application Programming Interface

REST and GraphQL API reference for 147 services: authentication, endpoints, rate limits, and per-service gotchas, plus pattern playbooks for everything that goes wrong between you and an API. User preferences live in ~/Clawic/data/api/ — the only location this skill writes (see setup.md on first use). If you have data at an old location (~/api/ or ~/clawic/api/), move it to ~/Clawic/data/api/.

When To Use

• User names a service to integrate ("call the Stripe API", "post to a Slack channel") → its section via API Categories below
• A request that "should work" returns 401/403/429, times out, or silently returns wrong data → debug.md and the pattern files
• Designing the client side of any integration: retries, pagination, webhooks, streaming, file transfer, async job polling
• Choosing between similar providers in a category (email, auth, media) → compare sections in the same category file
• Not for building your OWN API (routing, schema design, versioning your endpoints) — this skill documents consuming others' APIs

Quick Reference

API Categories

How to Navigate API Files

Each category file starts with an index table (API name → line number). Read the index, then only the section you need (50-100 lines each):

head -20 apis/ai-ml.md          # index
sed -n '139,251p' apis/ai-ml.md # one API's section (OpenAI, per the index)

Core Rules

1. Raw request before client code. Reproduce with curl first; if curl succeeds and the SDK fails, the bug is in SDK config (base URL, version pin, auth header name), not the API. Chains: debug.md.

2. Backoff with full jitter, and Retry-After overrides it. sleep = random(0, min(cap, base × 2^attempt)), base 1s, cap 30-60s, max retry_max attempts (default 4; AWS "full jitter"). Attempt 3 → sleep is a random value in [0, 8s], not exactly 8s — the randomness is what prevents synchronized retry storms. If the 429/503 carries Retry-After, obey it instead.

3. Retry only what cannot double-execute. GET/PUT/DELETE are idempotent; retry freely. POST only with an idempotency key — a 500 or timeout on POST may have committed server-side (the charge went through, the response didn't). Details and key lifetime: resilience.md.

4. Status triage in this order: 401 → credential, 403 → permission, 404 → maybe permission too. 401 = the API doesn't know who you are (missing/expired/malformed token). 403 = it knows you and says no (scope, plan tier, IP allowlist). Some APIs (GitHub among them) return 404 for resources you lack access to, to avoid confirming existence — a "not found" on a resource you know exists is an auth bug, not a URL bug.

5. HTTP 200 is not success. Check the body for error/errors fields (GraphQL always returns 200 — graphql.md), batch endpoints for per-item failures (207 Multi-Status or a 200 with a mixed results array — async-jobs.md), and streams for completion (streaming.md).

6. Both timeouts, always. Set connect and read timeouts explicitly; a request without them hangs forever on a dead upstream. Values and rationale: resilience.md; for streams, read timeout means inter-chunk idle (streaming.md).

7. Credentials in headers, never in URLs. Query-param keys land in access logs, proxy caches, and browser history. Env vars only; naming scheme for multi-account setups: credentials.md.

8. Paginate to completion or say you didn't. Terminate on the API's own signal (has_more, next cursor absent) — never on item count alone. If you stop early, state that results are partial.

Status Triage

Beyond Core Rule 4's 401/403/404 chain:

Output Gates

Before emitting integration code or a diagnosis, check:

• Every POST/PUT/PATCH example includes Content-Type: application/json (or the API's required type)
• No secret appears in a URL, code literal, or logged output — env var references only
• Every pagination loop terminates on the API's has_more/cursor signal, not on len(items)
• Retry logic distinguishes 4xx (don't retry, fix the request) from 429/5xx (backoff and retry)
• Webhook handler verifies signature on the raw body before parsing (→ webhooks.md)
• Money handled in the currency's own convention (minor units, exponent), IDs as strings (→ data-formats.md)
• Examples reference the default_environment credential (sandbox unless the user asked for live)

Configuration

User-dependent variables. Defaults apply until the user states a preference; store them in ~/Clawic/data/api/config.yaml (loading and recording procedure: setup.md).

Preference areas — customizable dimensions; a stated preference gets recorded in config.yaml and applied:

• Tooling: HTTP client library (requests/httpx, axios/fetch, net/http) and testing tool (curl, HTTPie, Postman) — shapes every snippet
• Integrations: the user's chosen provider per category (payments → Stripe, email → Postmark) — which service section answers a generic ask
• Conventions: credential env-var naming (default scheme: credentials.md), error-handling style (exceptions vs result values) — shapes generated code
• Thresholds: org-mandated timeouts and retry budgets — override the resilience.md defaults when stated
• Safety posture: whether examples may include write/mutating calls, confirm-before-live behavior — tightens or relaxes the environment gate
• Output format: snippet-only vs annotated walkthrough — answer verbosity

Traps

Where Experts Disagree

• Official SDK vs raw HTTP. SDKs win where auth is hard (request signing, OAuth refresh) and lose freshness — new endpoints land in the API before the SDK. Default: raw HTTP for simple bearer-token APIs; SDK when the provider signs requests or its docs treat the SDK as the primary interface. client_style records the user's side.
• Webhooks vs polling. Webhooks for volume and latency; polling is legitimately simpler when events are rare, no public endpoint can be hosted, or the poll interval is acceptable staleness. The wrong answer is webhooks without the full handler order (webhooks.md).
• Idempotency keys on every POST vs only where double-execution hurts. Every-POST buys uniform retry safety; minimalists note the bookkeeping cost. Boundary: any POST whose duplicate the user would notice (charge, email, order) gets a key — no exceptions there, optional elsewhere.

Security & Privacy

This skill is documentation: endpoint reference, auth patterns, and example requests for the external services listed above. Example endpoints belong to the respective providers (Stripe, OpenAI, etc.).

It does NOT:

• Store or manage API keys or secrets — it references env-var names; values are never read, printed, or persisted
• Make API calls on its own — the user runs the requests
• Send data to any external service

Guardrails:

• Credential discovery lists variable NAMES, never values (credentials.md Selection Rules)
• Sandbox/test credentials by default; live keys only on explicit user request
• Generated webhook handlers always verify signatures before parsing the payload

Related Skills

More Clawic skills, get them at https://clawic.com/skills/api (install if the user confirms):

• http — HTTP request patterns
• webhook — Webhook handling
• json — JSON processing

Feedback

• If useful, star it: https://clawic.com/skills/api
• Latest version: https://clawic.com/skills/api

---

Part of Clawic, the verified skill library. Get this skill: https://clawic.com/skills/api.