API / Application Programming Interface

Files (36)

• SKILL.md
• _meta.json
• ai-ml.md · apis/
• analytics.md · apis/
• auth-providers.md · apis/
• business.md · apis/
• communication.md · apis/
• crm.md · apis/
• database.md · apis/
• developer.md · apis/
• geo.md · apis/
• marketing.md · apis/
• media.md · apis/
• payments.md · apis/
• productivity.md · apis/
• realtime.md · apis/
• social.md · apis/
• support.md · apis/
• async-jobs.md
• auth.md
• browser.md
• caching.md
• credentials.md
• data-formats.md
• debug.md
• files.md
• graphql.md
• pagination.md
• rate-limits.md
• resilience.md
• setup.md
• streaming.md
• sync.md
• testing.md
• versioning.md
• webhooks.md

SKILL.md (first lines)

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/`, and say in one line that you moved it and from where.

## 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

| Situation | Read |
|-----------|------|
| Endpoints/auth for a named service | Its category file — API Categories table below |
| 401/403 that "should work", OAuth flow choice, JWT rejected | `auth.md` |
| Works in curl but not in code, works locally but not in prod, TLS errors, mysterious 400s | `debug.md` |
| Duplicated/missing items across pages, loop never ends | `pagination.md` |
| Timeouts, retries, flaky upstream, circuit breakers, provider outage | `resilience.md` |
| 429s, rate-limit headers, quota budgeting, spending less of the limit | `rate-limits.md` |
| Polling for changes, ETag/304 conditional requests, what to cache client-side | `caching.md` |
| Mirroring API data locally, incremental sync, detecting deletions, sync token expired | `sync.md` |
| Blocked by CORS, calling an API from frontend code, key would ship to the browser | `browser.md` |
| SSE stream buffers, hangs, or cuts off; events half-parsed; WebSocket drops | `streaming.md` |
| Receiving events, signature verification, duplicate deliveries | `webhooks.md` |
| Upload rejected with 400/411/413, download corrupted or truncated, presigned URLs | `files.md` |
| 202 Accepted, job polling, batch partial failures, async exports | `async-jobs.md` |
| The service speaks GraphQL (GitHub v4, Shopify, Linear) | `graphql.md` |
| Version pinning, `Sunset`/`Deprecation` headers, provider changed the API | `versioning.md` |
| Sandbox vs live, mocking providers, recorded fixtures, contract drift | `testing.md` |
| Money amounts, timestamps, big numeric IDs, unicode limits in payloads | `data-formats.md` |
| Multiple accounts/keys for one service | `credentials.md` |
| Anything else | Core Rules below, then the Official Docs link at the end of each API section |

## API Categories

| Category | File | Services |
|----------|------|----------|
| AI/ML | `apis/ai-ml.md` | anthropic, openai, cohere, groq, mistral, perplexity, huggingface, replicate, stability, elevenlabs, deepgram, assemblyai, together, anyscale |
| Payments | `apis/payments.md` | stripe, paypal, square, plaid, chargebee, paddle, lemonsqueezy, recurly, wise, coinbase, binance, alpaca, polygon |
| Communication | `apis/communication.md` | twilio, sendgrid, mailgun, postmark, resend, mailchimp, slack, discord, telegram, zoom |
| Realtime | `apis/realtime.md` | sendbird, stream-chat, pusher, ably, onesignal, courier, knock, novu |
| CRM | `apis/crm.md` | salesforce, hubspot, pipedrive, attio, close, apollo, outreach, gong |
| Marketing | `apis/marketing.md` | drift, crisp, front, customer-io, braze, iterable, klaviyo |
| Developer | `apis/developer.md` | github, gitlab, bitbucket, vercel, netlify, railway, render, fly, digitalocean, heroku, cloudflare, circleci, pagerduty, launchdarkly, split, statsig |
| Database | `apis/database.md` | supabase, firebase, planetscale, neon, upstash, mongodb, fauna, xata, convex, appwrite |
| Auth | `apis/auth-providers.md` | clerk, auth0, workos, stytch |
| Media | `apis/media.md` | cloudinary, mux, bunny, imgix, uploadthing, uploadcare, transloadit, vimeo, youtube, spotify, unsplash, pexels, giphy, tenor |
| Social | `apis/social.md` | twitter, linkedin, instagram, tiktok, pinterest, reddit, twitch |
| Productivity | `apis/productivity.md` | notion, airtable, google-sheets, google-drive, google-calendar, dropbox, linear, jira, asana, trello, monday, clickup, figma, calendly, cal, loom, typeform |
| Business | `apis/business.md` | shopify, docusign, hellosign, bitly, dub |
| Geo | `apis/geo.md` | openweather, mapbox, google-maps |
| Support | `apis/support.md` | intercom, zendesk, freshdesk, helpscout |
| Analytics | `apis/analytics.md` | mixpanel, amplitude, posthog, segment, sentry, datadog, algolia |

## 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):

```bash
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:

| Code | Meaning | First move |
|------|---------|-----------|
| 400 | Request malformed or rejected | Read the body's error field, then `debug.md` Mysterious 400s |
| 405 | Method not allowed | Wrong verb — or a redirect: clients follow 301/302 on POST by re-issuing GET (trailing-slash URLs are the classic trigger) |
| 409 | State conflict | Re-fetch current state; concurrent edit or duplicate create |
| 410 | Gone permanently | Retired resource or API version (`versioning.md`); expired sync token (`sync.md` Sync Tokens) |
| 412 | Precondition failed | Your `If-Match` ETag is stale — re-read, re-apply, retry |
| 415 | Unsupported media type | `Content-Type` missing or wrong (top trap below) |
| 422 | Validation failed | Well-formed but semantically rejected — field-level errors are in the body |
| 429 | Rate limited | `rate-limits.md`; obey `Retry-After` |
| 500 | Server bug | Retry only idempotent requests (`resilience.md` Retry Logic) |
| 502/503/504 | Edge/LB failure or overload, often with an HTML body | Backoff and retry; check the status page (`resilience.md` Provider Outages) |

## 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`).

| Variable | Type | Default | Effect |
|---|---|---|---|
| example_language | curl \| python \| javascript \| go | curl | Language every request example is rendered in, across all category and pattern files |
| client_style | raw \| sdk | raw | Whether examples use raw HTTP or the provider's official SDK (tradeoff: Where Experts Disagree) |

From clawic/skills, MIT.

More from clawic/skills