# Build with AI agents

Docs

Everything a coding agent needs to integrate the API correctly on the first try: a prompt to paste, the rules to follow, an Agent Skill and Markdown docs.

SocialTap is built to be integrated by AI coding agents such as Claude Code, Cursor or Codex. Every docs page is also Markdown, the whole documentation is one file, and the rules below are generated from the same catalog as the API, so they are always current.

## Paste this into your agent

Give your agent this prompt to integrate SocialTap into your project. It sends the agent to the docs first and ends with a real request, so you see it working:

Prompt:

```
Integrate the SocialTap API (https://staging.socialtap.dev) into this project.

1. Read https://staging.socialtap.dev/llms.txt first, then the Markdown docs page of the endpoint you need (linked there). Use only endpoints and parameters documented there.
2. Send the API key in the x-api-key header, read from the SOCIALTAP_API_KEY environment variable. Never hard-code it; if it is not set, ask me for it.
3. Branch on error.code: retry only the retryable codes the docs list, with backoff. On list endpoints follow page.next_cursor while page.has_more is true.
4. Verify with one real request before building on it, for example:

   curl -G 'https://staging.socialtap.dev/v1/youtube/transcript' \
     --data-urlencode 'url=dQw4w9WgXcQ' \
     -H "x-api-key: $SOCIALTAP_API_KEY"

   and check that data is not empty.
5. Tell me which endpoint you used, what meta.credits_charged was, and any error code you saw.
```

## Instructions for AI agents

The same rules open [llms.txt](https://staging.socialtap.dev/llms.txt) and the Agent Skill:

1. **Authenticate.** Send the API key in the `x-api-key` header of every request to `https://staging.socialtap.dev`. Read it from an environment variable such as `SOCIALTAP_API_KEY`, never hard-code it, and call the API from server-side code only. Without a key, ask the user for one (keys: [https://staging.socialtap.dev/signup/](https://staging.socialtap.dev/signup/)); never invent one.
2. **No key yet?** `POST https://staging.socialtap.dev/v1/agent_signup` with `{"email": "<your user's email>"}` returns a test key that works at once and a live key that stays pending until your user confirms the emailed link (it spends nothing until then). Ask the user for their email address first, build with the test key, and tell them to confirm. Details: [account and keys](https://staging.socialtap.dev/docs/account/index.md).
3. **Pick an endpoint.** Every endpoint is `GET https://staging.socialtap.dev/v1/<platform>/<name>` with query parameters; the endpoint list ([all endpoints](https://staging.socialtap.dev/apis/index.md), or [catalog.json](https://staging.socialtap.dev/catalog.json) for machines) gives each one's parameters and price per successful request. Read the endpoint's Markdown docs page before writing code, and don't rely on memory: endpoints and parameters change. Every endpoint of one kind of data (ads, comments, posts, profiles and transcripts) returns the same schema on every platform; `null` means unknown, never 0 or "".
4. **Read the response.** A success is HTTP 200 with `{data, meta}`: `meta.credits_charged` is what the request cost, `meta.credits_remaining` the balance left, `meta.request_id` identifies the request for support.
5. **Paginate.** List endpoints return `{data, page, meta}`. While `page.has_more` is true, repeat the same request with `cursor` set to `page.next_cursor`, keeping every other parameter. An empty page with `page.has_more` true is not the end. Cursors expire (`page.next_cursor_expires_at`): don't store them. Leave `limit` out: a smaller page costs the same.
6. **Handle errors.** Errors are non-2xx responses with `{"error": {code, message, request_id, status, retryable, param, remediation, doc_url, details, charged}}`. Branch on `error.code`, never on `error.message`. Retry only when `error.retryable` is true, with exponential backoff, first waiting the seconds in the `retry-after` header (also `error.details.retry_after`) when it is sent; otherwise do what `error.remediation` says. `insufficient_credits` means the balance is too low: stop and tell the user. Every code is documented at `https://staging.socialtap.dev/docs/errors/#<code>` (`error.doc_url`). Failed requests cost nothing.
7. **Spend credits deliberately.** Each endpoint states its price per successful request (per page for lists); fetch only what the task needs. Add `max_age=<seconds>` to accept a stored response up to that old: cache hits are free.
8. **Test first.** Keys starting with `st_test_` are test keys: they answer every endpoint from recorded responses, free and deterministic. Build and test the integration with one, then switch to a live key. Magic inputs make an endpoint return any error code it can return ([test mode](https://staging.socialtap.dev/docs/test-mode/index.md)), so test your error handling too.
9. **Many items or long lists.** Use background jobs, `POST /v1/jobs`, instead of a loop of single requests: one job runs many requests and walks whole lists.
10. **Notifications.** Instead of polling, register a webhook endpoint with `POST /v1/webhook_endpoints`: deliveries are signed (Standard Webhooks); verify the signature on the raw body before trusting one.
11. **Retry POSTs safely.** Send a new `idempotency-key` (a UUID) with every POST and reuse it when you retry: the work runs once, and a retry answers with the current state.
12. **Balance.** `GET /v1/account` returns the balance, free.
13. **MCP.** Agents with MCP can use the remote server at `https://staging.socialtap.dev/mcp` (Streamable HTTP, the same API key as `authorization: Bearer <key>` or in the `x-api-key` header), with the tools `get_post`, `get_profile`, `get_transcript`, `list_comments`, `search`, `find_endpoint`, `get_account`, `create_job` and `get_job`; see [the agent guide](https://staging.socialtap.dev/docs/agents/index.md).
14. **Verify.** Before building on an endpoint, run its example request (on its docs page) and check that `data` is not empty. Report the endpoint, `meta.credits_charged` and any `error.code` you saw.

## Which endpoint

| Data | Request | Price | Docs |
| --- | --- | --- | --- |
| Facebook · Ads (beta) | `GET /v1/facebook/search_ads` | 1 credit (api) per page | [docs](https://staging.socialtap.dev/apis/facebook/search_ads/index.md) |
| Facebook · Transcript (beta) | `GET /v1/facebook/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/facebook/transcript/index.md) |
| Instagram · Post (beta) | `GET /v1/instagram/post` | 1 credit (page) per request | [docs](https://staging.socialtap.dev/apis/instagram/post/index.md) |
| Instagram · Transcript (beta) | `GET /v1/instagram/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/instagram/transcript/index.md) |
| TikTok · Profile (beta) | `GET /v1/tiktok/profile` | 1 credit (page) per request | [docs](https://staging.socialtap.dev/apis/tiktok/profile/index.md) |
| TikTok · Transcript (beta) | `GET /v1/tiktok/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/tiktok/transcript/index.md) |
| YouTube · Comments (beta) | `GET /v1/youtube/comments` | 1 credit (api) per page | [docs](https://staging.socialtap.dev/apis/youtube/comments/index.md) |
| YouTube · Transcript (beta) | `GET /v1/youtube/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/youtube/transcript/index.md) |

## Docs for agents

- [llms.txt](https://staging.socialtap.dev/llms.txt): the instructions above and a link to every page, as Markdown.
- [llms-full.txt](https://staging.socialtap.dev/llms-full.txt): every guide and endpoint reference in one Markdown file.
- Every page has a Markdown twin: add `index.md` to its URL, or request the page with `Accept: text/markdown`. Each page also has "Copy page as Markdown" and "Open in Claude / ChatGPT" buttons.
- The [API reference](https://staging.socialtap.dev/docs/reference/index.md): every operation on one page, readable without JavaScript.
- [openapi.json](https://staging.socialtap.dev/openapi.json): OpenAPI 3.1 with examples, the exact errors of each operation and `x-socialtap-*` extensions for pricing, pagination and retries.

## Agent Skill

The skill is published at [`https://staging.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md`](https://staging.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md) and listed in the [Agent Skills discovery index](https://staging.socialtap.dev/.well-known/agent-skills/index.json). It follows the open [Agent Skills](https://agentskills.io/specification) format, so any agent that loads skills can use it. For Claude Code, add it to a project:

Shell:

```shell
mkdir -p .claude/skills/socialtap && curl -fsSL https://staging.socialtap.dev/.well-known/agent-skills/socialtap/SKILL.md -o .claude/skills/socialtap/SKILL.md
```

**Show the generated SKILL.md**

SKILL.md:

````markdown
---
name: socialtap
description: "Fetch public social media data (ads, comments, posts, profiles and transcripts) from Facebook, Instagram, TikTok and YouTube with the SocialTap API: one API key, one JSON schema per kind of data, pay per successful request. Use when the user asks to get, scrape, download or analyze ads, comments, posts, profiles and transcripts from Facebook, Instagram, TikTok and YouTube, or to build code that does."
metadata:
  homepage: "https://staging.socialtap.dev"
  docs: "https://staging.socialtap.dev/llms.txt"
---

# SocialTap

SocialTap returns public social media data (transcripts today; profiles, posts and comments next) from every major platform through one API key, one credit balance and one response schema per resource.

## How to use the API

1. **Authenticate.** Send the API key in the `x-api-key` header of every request to `https://staging.socialtap.dev`. Read it from an environment variable such as `SOCIALTAP_API_KEY`, never hard-code it, and call the API from server-side code only. Without a key, ask the user for one (keys: https://staging.socialtap.dev/signup/); never invent one.
2. **No key yet?** `POST https://staging.socialtap.dev/v1/agent_signup` with `{"email": "<your user's email>"}` returns a test key that works at once and a live key that stays pending until your user confirms the emailed link (it spends nothing until then). Ask the user for their email address first, build with the test key, and tell them to confirm. Details: [account and keys](https://staging.socialtap.dev/docs/account/index.md).
3. **Pick an endpoint.** Every endpoint is `GET https://staging.socialtap.dev/v1/<platform>/<name>` with query parameters; the endpoint list ([all endpoints](https://staging.socialtap.dev/apis/index.md), or [catalog.json](https://staging.socialtap.dev/catalog.json) for machines) gives each one's parameters and price per successful request. Read the endpoint's Markdown docs page before writing code, and don't rely on memory: endpoints and parameters change. Every endpoint of one kind of data (ads, comments, posts, profiles and transcripts) returns the same schema on every platform; `null` means unknown, never 0 or "".
4. **Read the response.** A success is HTTP 200 with `{data, meta}`: `meta.credits_charged` is what the request cost, `meta.credits_remaining` the balance left, `meta.request_id` identifies the request for support.
5. **Paginate.** List endpoints return `{data, page, meta}`. While `page.has_more` is true, repeat the same request with `cursor` set to `page.next_cursor`, keeping every other parameter. An empty page with `page.has_more` true is not the end. Cursors expire (`page.next_cursor_expires_at`): don't store them. Leave `limit` out: a smaller page costs the same.
6. **Handle errors.** Errors are non-2xx responses with `{"error": {code, message, request_id, status, retryable, param, remediation, doc_url, details, charged}}`. Branch on `error.code`, never on `error.message`. Retry only when `error.retryable` is true, with exponential backoff, first waiting the seconds in the `retry-after` header (also `error.details.retry_after`) when it is sent; otherwise do what `error.remediation` says. `insufficient_credits` means the balance is too low: stop and tell the user. Every code is documented at `https://staging.socialtap.dev/docs/errors/#<code>` (`error.doc_url`). Failed requests cost nothing.
7. **Spend credits deliberately.** Each endpoint states its price per successful request (per page for lists); fetch only what the task needs. Add `max_age=<seconds>` to accept a stored response up to that old: cache hits are free.
8. **Test first.** Keys starting with `st_test_` are test keys: they answer every endpoint from recorded responses, free and deterministic. Build and test the integration with one, then switch to a live key. Magic inputs make an endpoint return any error code it can return ([test mode](https://staging.socialtap.dev/docs/test-mode/index.md)), so test your error handling too.
9. **Many items or long lists.** Use background jobs, `POST /v1/jobs`, instead of a loop of single requests: one job runs many requests and walks whole lists.
10. **Notifications.** Instead of polling, register a webhook endpoint with `POST /v1/webhook_endpoints`: deliveries are signed (Standard Webhooks); verify the signature on the raw body before trusting one.
11. **Retry POSTs safely.** Send a new `idempotency-key` (a UUID) with every POST and reuse it when you retry: the work runs once, and a retry answers with the current state.
12. **Balance.** `GET /v1/account` returns the balance, free.
13. **MCP.** Agents with MCP can use the remote server at `https://staging.socialtap.dev/mcp` (Streamable HTTP, the same API key as `authorization: Bearer <key>` or in the `x-api-key` header), with the tools `get_post`, `get_profile`, `get_transcript`, `list_comments`, `search`, `find_endpoint`, `get_account`, `create_job` and `get_job`; see [the agent guide](https://staging.socialtap.dev/docs/agents/index.md).
14. **Verify.** Before building on an endpoint, run its example request (on its docs page) and check that `data` is not empty. Report the endpoint, `meta.credits_charged` and any `error.code` you saw.

## Endpoints

| Data | Request | Price | Docs |
| --- | --- | --- | --- |
| Facebook · Ads (beta) | `GET /v1/facebook/search_ads` | 1 credit (api) per page | [docs](https://staging.socialtap.dev/apis/facebook/search_ads/index.md) |
| Facebook · Transcript (beta) | `GET /v1/facebook/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/facebook/transcript/index.md) |
| Instagram · Post (beta) | `GET /v1/instagram/post` | 1 credit (page) per request | [docs](https://staging.socialtap.dev/apis/instagram/post/index.md) |
| Instagram · Transcript (beta) | `GET /v1/instagram/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/instagram/transcript/index.md) |
| TikTok · Profile (beta) | `GET /v1/tiktok/profile` | 1 credit (page) per request | [docs](https://staging.socialtap.dev/apis/tiktok/profile/index.md) |
| TikTok · Transcript (beta) | `GET /v1/tiktok/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/tiktok/transcript/index.md) |
| YouTube · Comments (beta) | `GET /v1/youtube/comments` | 1 credit (api) per page | [docs](https://staging.socialtap.dev/apis/youtube/comments/index.md) |
| YouTube · Transcript (beta) | `GET /v1/youtube/transcript` | 1 credit (captions); 2 credits + 2 per started minute of media (asr) per request | [docs](https://staging.socialtap.dev/apis/youtube/transcript/index.md) |

## Example

```shell
curl -G 'https://staging.socialtap.dev/v1/youtube/transcript' \
  --data-urlencode 'url=dQw4w9WgXcQ' \
  -H "x-api-key: $SOCIALTAP_API_KEY"
```

## More

- Docs index for agents: https://staging.socialtap.dev/llms.txt; everything in one file: https://staging.socialtap.dev/llms-full.txt
- API reference: https://staging.socialtap.dev/docs/reference/index.md; OpenAPI: https://staging.socialtap.dev/openapi.json
- Error codes: https://staging.socialtap.dev/docs/errors/index.md
````

## MCP server

The remote MCP server at `https://staging.socialtap.dev/mcp` (Streamable HTTP) takes your API key as `authorization: Bearer <key>` or in the `x-api-key` header, and each tool call costs what the same API request costs. Set `SOCIALTAP_API_KEY` in your environment, then add the server:

Claude Code:

```shell
claude mcp add --transport http socialtap https://staging.socialtap.dev/mcp --header "authorization: Bearer $SOCIALTAP_API_KEY"
```

Claude Code (.mcp.json):

```json
{
  "mcpServers": {
    "socialtap": {
      "type": "http",
      "url": "https://staging.socialtap.dev/mcp",
      "headers": {
        "authorization": "Bearer ${SOCIALTAP_API_KEY}"
      }
    }
  }
}
```

Cursor (mcp.json):

```json
{
  "mcpServers": {
    "socialtap": {
      "url": "https://staging.socialtap.dev/mcp",
      "headers": {
        "authorization": "Bearer ${env:SOCIALTAP_API_KEY}"
      }
    }
  }
}
```

Codex:

```shell
codex mcp add socialtap --url https://staging.socialtap.dev/mcp --bearer-token-env-var SOCIALTAP_API_KEY
```

Codex (config.toml):

```toml
[mcp_servers.socialtap]
url = "https://staging.socialtap.dev/mcp"
bearer_token_env_var = "SOCIALTAP_API_KEY"
```

Its tools cover every endpoint, grouped by resource: pass `platform` and the link, handle or query. Results are concise JSON (`detail: "full"` returns every field), state `credits_charged` and `credits_remaining`, and are cut at about 20,000 tokens with a `next_cursor` to continue. Listing the tools and `find_endpoint` work without a key.

| Tool | What it does |
| --- | --- |
| `get_post` | Get a public post on Instagram. |
| `get_profile` | Get a public profile on TikTok. |
| `get_transcript` | Get the transcript of a public video or post on Facebook, Instagram, TikTok or YouTube. |
| `list_comments` | List the comments of a public post on YouTube, one page per call. |
| `search` | Search public ads on Facebook by query. |
| `find_endpoint` | Find which SocialTap tool and endpoint serves a need ("TikTok comments", "YouTube transcript") or a link: returns the best matches with the tool and arguments to call, the price, the parameters and an example result. |
| `get_account` | Get the account, balance and calling key. |
| `create_job` | Run many requests (or one long one) as a job. |
| `get_job` | Get a job (free to poll). |

---

[HTML version](https://staging.socialtap.dev/docs/agents/) · [Docs index for AI agents](https://staging.socialtap.dev/llms.txt) · [All docs in one file](https://staging.socialtap.dev/llms-full.txt)