AI Agent Integration
Machine-readable discovery files, Markdown twins, and the OpenAPI spec that let an agent learn the API on its own
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 request.
If you only wire up one thing, point your agent at
/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 (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 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. Depending on the endpoint, these fields can include engagement_rate, language, content_category, and estimated_reach. See Computed fields.
How do AI agents discover SocialCrawl?
Four machine-readable files describe the API, in increasing detail. Point your agent at /llms-full.txt for everything it needs: the entire 679-endpoint catalogue is included.
| File | What it holds |
|---|---|
/llms.txt | Compact overview of the API |
/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 | Machine-readable catalog: per-platform endpoint counts, auth, credit tiers, response envelope |
/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:
/docsbecomes/docs.md/docs/quickstartbecomes/docs/quickstart.md/docs/api-referencebecomes/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.
How can agents use the OpenAPI specification?
The full OpenAPI 3.1 specification is available in both formats:
The full spec covers every endpoint, so it is large. When you need one platform, fetch its own OpenAPI document instead, for example /openapi/tiktok.json: the same contract for that platform's endpoints, a few MB at most. /openapi/index.json lists every document with its endpoint count. Code generators and Postman imports work the same way.
Discover's whole lifecycle (the call, its 202 answer, the run routes, resume, cancel and results.jsonl) has its own OpenAPI 3.1 slice at /openapi/prism-discover.json.
Which endpoint answers a question about several platforms?
To search one platform, call that platform's own search. To search several platforms over a date window with every row judged and de-duplicated, call /v1/prism/discover. For a quick fused sweep at a flat 20 credits, call /v1/search/everywhere, which drops rows outside from_date, to_date, since or until but reads one page per source, so a past window can come back thin. Discover answers in the call, or answers 202 with a run the agent follows at data.next.status_url, so one call always works. Discover for agents has the two tool definitions, the retry policy and three worked transcripts.
Which endpoint finds creators or influencers?
To find creators or influencers (by topic, market, size, or a product to promote), lookalikes of creators, or to measure and rank a list of creators you already have, call /v1/prism/creators. For shops, businesses and sellers, call /v1/prism/discover with view=accounts. It answers in the call, or answers 202 with a run the agent follows at data.next.status_url. Creator search has the two agent tools, the retry policy and the canonical requests, and its whole lifecycle has its own OpenAPI 3.1 slice at /openapi/prism-creators.json.
Which call tells an agent when something new appears?
To be told when something new appears, match the ask to its job: for a recurring digest of what is new about a topic, keyword or brand, every 1h or slower, call POST /v1/prism/discover with schedule (every 1h or slower, dry_run first), read through GET /v1/events or a webhook endpoint; for the new posts or comments of an account or post you already know, call POST /v1/monitors with webhook_rows: "new"; for a one-off check of what is new since your last check, on an endpoint that takes since or since_id, call the endpoint's own since or since_id (for example GET /v1/twitter/tweet/replies with since_id, which returns an empty list and costs nothing when nothing is new); for metric snapshots of accounts you name (followers, views, likes), taken on a schedule, call POST /v1/monitors with a track metric; for reading what your watches produced, from a feed you poll or an endpoint that receives a signed push, call GET /v1/events with a named consumer for reading, and /v1/webhook-endpoints for push; for what a keyword or boolean topic listener would cost each month and how it reads the rule, before it is created, call POST /v1/listening/streams?dry_run=1 with the listener body, which costs 0 credits and creates nothing; for each new mention of keywords or a boolean topic delivered one by one, every 30 minutes or slower, with boolean groups, a monthly cap and usage per client, and with comments: "new_posts" the comments under the Reddit posts it keeps, call POST /v1/listening/streams?dry_run=1 to price it, then POST /v1/listening/streams to create the listener; for the new posts of up to 1,000 named business, brand, creator or organisation accounts that match a topic, every 30 minutes or slower, call POST /v1/listening/streams?dry_run=1 with accounts (each a platform:handle such as reddit:nasa or youtube:@Google, or a profile URL), schedule.purpose (business, brand, creator or organisation) and keywords, then POST /v1/listening/streams to create the listener; for what is new on your listeners since the last read, in a later session or on a schedule you run yourself, call GET /v1/events with a named consumer and types=mention.*, then acknowledge each page with its pagination.next_cursor. A watch checks on a schedule and reports what that check found. Read what a watch produced with the event feed or receive it at a signed webhook endpoint; the schedule is explained in discover schedules and the account watch in Monitor webhooks.
How does an agent find out that something needs its attention?
Read GET /v1/notifications?unread=true once a minute or less. It lists a paused Monitor webhook, a failed Discover run, a call refused for credits and similar items, each with a plain title, message and one concrete next_step, so the agent does not have to know the kinds. After it acts, it sends the item ids to POST /v1/notifications/read. Both calls are free. See Notifications.
What per-platform documentation is available?
Fetch only the endpoints you need. There is one file per active platform.
Each file contains only that platform's endpoints, with parameters, descriptions, and cURL examples. /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.
const apiKey = process.env.SOCIALCRAWL_API_KEY;
if (!apiKey) throw new Error("Set SOCIALCRAWL_API_KEY");Call the endpoint with x-api-key
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
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 reasoningNever 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 page.
Troubleshooting
Official AI framework documentation
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.
# 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.