# AI Agent Integration (/docs/ai-agents)

Machine-readable discovery files, Markdown twins, and the OpenAPI spec that let an agent learn the API on its own

SocialCrawl is built to be consumed by AI agents. Every response is the same JSON envelope, every endpoint takes one header, and the whole catalogue is published as machine-readable files an agent can read before it writes a single request.

  If you only wire up one thing, point your agent at
  [`/llms-full.txt`](/llms-full.txt). It is the complete, self-contained
  reference.

## Prerequisites

- Nothing to install. Every discovery file below is public and needs no key.
- An API key from [socialcrawl.dev](https://www.socialcrawl.dev) (Dashboard → API Keys) for any call that returns data. New accounts start with 100 free credits.
- Using an MCP client or an agent skill instead? [Skills & MCP](/docs/skills-and-mcp.md) is a one-line setup that skips the plumbing on this page.

When an endpoint supports a computed field and the required source inputs are present, its response includes that optional field for downstream reasoning. Depending on the endpoint, these fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md).

## How do AI agents discover SocialCrawl?

Four machine-readable files describe the API, in increasing detail. Point your agent at [`/llms-full.txt`](/llms-full.txt) for everything it needs: the entire 646-endpoint catalogue is included.

| File                               | What it holds                                                                                                                                              |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](/llms.txt)           | Compact overview of the API                                                                                                                                |
| [`/llms-full.txt`](/llms-full.txt) | Complete self-contained reference, including the `GET /v1/credits/balance` meta endpoint, idempotency semantics, `oneOf` constraints, and every error code |
| [`/llms.json`](/llms.json)         | Machine-readable catalog: per-platform endpoint counts, auth, credit tiers, response envelope                                                              |
| [`/agents.txt`](/agents.txt)       | AI agent access file: capabilities, quick start, and crawl guidance in one place                                                                           |

## How do I read a docs page as Markdown?

Append `.md` to any docs URL:

- `/docs` becomes [`/docs.md`](/docs.md)
- `/docs/quickstart` becomes [`/docs/quickstart.md`](/docs/quickstart.md)
- `/docs/api-reference` becomes [`/docs/api-reference.md`](/docs/api-reference.md)

You can also send `Accept: text/markdown` on the HTML URL. Every docs page carries an "AI agent or LLM? Read this page as markdown" link pointing at the same twin. Twins are served as `text/plain`, marked `X-Robots-Tag: noindex`, and listed in [`/sitemaps/llm.xml`](/sitemaps/llm.xml).

## How can agents use the OpenAPI specification?

The full OpenAPI 3.1 specification is available in both formats:

- [`/v1/openapi.json`](/v1/openapi.json)
- [`/v1/openapi.yaml`](/v1/openapi.yaml)

## What per-platform documentation is available?

Fetch only the endpoints you need. There is one file per active platform.

| Platform         | Reference File                                             |
| ---------------- | ---------------------------------------------------------- |
| TikTok           | [`/llms-tiktok.txt`](/llms-tiktok.txt)                     |
| Instagram        | [`/llms-instagram.txt`](/llms-instagram.txt)               |
| YouTube          | [`/llms-youtube.txt`](/llms-youtube.txt)                   |
| Facebook         | [`/llms-facebook.txt`](/llms-facebook.txt)                 |
| Twitter/X        | [`/llms-twitter.txt`](/llms-twitter.txt)                   |
| LinkedIn         | [`/llms-linkedin.txt`](/llms-linkedin.txt)                 |
| Reddit           | [`/llms-reddit.txt`](/llms-reddit.txt)                     |
| Threads          | [`/llms-threads.txt`](/llms-threads.txt)                   |
| Bluesky          | [`/llms-bluesky.txt`](/llms-bluesky.txt)                   |
| Pinterest        | [`/llms-pinterest.txt`](/llms-pinterest.txt)               |
| Snapchat         | [`/llms-snapchat.txt`](/llms-snapchat.txt)                 |
| Truth Social     | [`/llms-truthsocial.txt`](/llms-truthsocial.txt)           |
| Twitch           | [`/llms-twitch.txt`](/llms-twitch.txt)                     |
| Kick             | [`/llms-kick.txt`](/llms-kick.txt)                         |
| Rumble           | [`/llms-rumble.txt`](/llms-rumble.txt)                     |
| Kwai             | [`/llms-kwai.txt`](/llms-kwai.txt)                         |
| Spotify          | [`/llms-spotify.txt`](/llms-spotify.txt)                   |
| Apple Music      | [`/llms-apple_music.txt`](/llms-apple_music.txt)           |
| GitHub           | [`/llms-github.txt`](/llms-github.txt)                     |
| Hacker News      | [`/llms-hackernews.txt`](/llms-hackernews.txt)             |
| Naver            | [`/llms-naver.txt`](/llms-naver.txt)                       |
| Polymarket       | [`/llms-polymarket.txt`](/llms-polymarket.txt)             |
| Amazon           | [`/llms-amazon.txt`](/llms-amazon.txt)                     |
| Walmart          | [`/llms-walmart.txt`](/llms-walmart.txt)                   |
| Target           | [`/llms-target.txt`](/llms-target.txt)                     |
| eBay             | [`/llms-ebay.txt`](/llms-ebay.txt)                         |
| Home Depot       | [`/llms-home_depot.txt`](/llms-home_depot.txt)             |
| Wayfair          | [`/llms-wayfair.txt`](/llms-wayfair.txt)                   |
| TikTok Shop      | [`/llms-tiktokshop.txt`](/llms-tiktokshop.txt)             |
| Google Shopping  | [`/llms-google_shopping.txt`](/llms-google_shopping.txt)   |
| Google Play      | [`/llms-google_play.txt`](/llms-google_play.txt)           |
| Apple App Store  | [`/llms-app_store.txt`](/llms-app_store.txt)               |
| Trustpilot       | [`/llms-trustpilot.txt`](/llms-trustpilot.txt)             |
| Tripadvisor      | [`/llms-tripadvisor.txt`](/llms-tripadvisor.txt)           |
| Google           | [`/llms-google.txt`](/llms-google.txt)                     |
| Google News      | [`/llms-google_news.txt`](/llms-google_news.txt)           |
| Google Finance   | [`/llms-google_finance.txt`](/llms-google_finance.txt)     |
| Google Trends    | [`/llms-google_trends.txt`](/llms-google_trends.txt)       |
| Perplexity       | [`/llms-perplexity.txt`](/llms-perplexity.txt)             |
| Tavily           | [`/llms-tavily.txt`](/llms-tavily.txt)                     |
| Web Scraping     | [`/llms-web.txt`](/llms-web.txt)                           |
| Content Analysis | [`/llms-content_analysis.txt`](/llms-content_analysis.txt) |
| Universal Search | [`/llms-search.txt`](/llms-search.txt)                     |
| Prism composites | [`/llms-prism.txt`](/llms-prism.txt)                       |
| Utility          | [`/llms-utility.txt`](/llms-utility.txt)                   |
| Linktree         | [`/llms-linktree.txt`](/llms-linktree.txt)                 |
| LinkBio          | [`/llms-linkbio.txt`](/llms-linkbio.txt)                   |
| LinkMe           | [`/llms-linkme.txt`](/llms-linkme.txt)                     |
| Komi             | [`/llms-komi.txt`](/llms-komi.txt)                         |
| Pillar           | [`/llms-pillar.txt`](/llms-pillar.txt)                     |

Each file contains only that platform's endpoints, with parameters, descriptions, and cURL examples. [`/llms.txt`](/llms.txt) links the current list; treat that as the source of truth if this table ever trails a new platform launch.

## How do I integrate SocialCrawl with my AI agent?

### Read your key from the environment

Never inline a key in agent code or a prompt.

```typescript title="TypeScript"
const apiKey = process.env.SOCIALCRAWL_API_KEY;
if (!apiKey) throw new Error("Set SOCIALCRAWL_API_KEY");
```

### Call the endpoint with `x-api-key`

```typescript title="TypeScript"
const response = await fetch(
  "https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio",
  { headers: { "x-api-key": apiKey } },
);
const json = await response.json();
```

### Branch on `success` before you hand anything to the model

```typescript title="TypeScript"
if (!json.success) {
  // Machine-readable failure: branch on error.type, follow error.doc_url.
  throw new Error(`${json.error.type}: ${json.error.message}`);
}
// json.data is structured and ready for AI reasoning
```

Never hand a raw `{ "success": false, ... }` envelope back to a model as if it were data. It will reason around the error instead of retrying or reporting it. Use `error.type` to decide what to do, and honour the `Retry-After` header on a `429` or `503`. The full list is on the [Errors](/docs/errors.md) page.

## Troubleshooting

It is guessing rather than reading. Give it [`/llms-full.txt`](/llms-full.txt), or the single platform file it needs, before it plans a call. An MCP client gets this for free: the server validates the platform, endpoint, and required parameters locally and refuses a bad call without spending a credit.

Its tool wrapper is returning the whole envelope. Check `success` inside the tool and return a short directive instead, for example `SocialCrawl error NOT_FOUND: ... See <doc_url>`. The [LangChain](/docs/langchain.md) and [Vercel AI SDK](/docs/vercel-ai-sdk.md) pages show the pattern.

Read `credits_remaining` from the envelope after each call and stop on a budget. Cap the tool loop as well: both framework pages set an explicit step limit. Empty results and upstream errors are auto-refunded, but a retry storm on a valid endpoint is not.

The `.md` suffix goes on the path, not the query string: `/docs/quickstart.md`, not `/docs/quickstart?format=md`. Sending `Accept: text/markdown` on the HTML URL works too.

## Official AI framework documentation

- [Anthropic Claude tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use)
- [OpenAI function calling](https://platform.openai.com/docs/guides/function-calling)
- [Vercel AI SDK](https://sdk.vercel.ai/docs)
- [LangChain](https://python.langchain.com/docs/introduction/)

## Which calls should an agent make before it writes code?

Three free calls replace guessing. Each costs 0 credits, answers in about 150 ms, and is generated from the endpoint registry at request time, so an agent that reads them never invents a path or a parameter.

```bash title="cURL"
# Find the endpoint for a job
curl "https://www.socialcrawl.dev/v1/utility/endpoints?search=comments" \
  -H "x-api-key: YOUR_API_KEY"

# Read its exact parameters, cost, paging rule, and an example call
curl "https://www.socialcrawl.dev/v1/utility/endpoint?id=tiktok/post/comments" \
  -H "x-api-key: YOUR_API_KEY"

# Confirm the key works and see the balance
curl "https://www.socialcrawl.dev/v1/credits/balance" \
  -H "x-api-key: YOUR_API_KEY"
```

Put those three lines at the top of any agent prompt or system instruction that touches SocialCrawl. The MCP server and the Agent Skill already do this before every request.

## Next steps

- [Skills & MCP](/docs/skills-and-mcp.md): One-line setup for any MCP client or agent skill.
- [LangChain](/docs/langchain.md): Wrap the API in a single LangChain tool.
- [Vercel AI SDK](/docs/vercel-ai-sdk.md): The same pattern with tool() and generateText.
- [Errors](/docs/errors.md): Every error type, what it means, and whether to retry.