# SocialCrawl API: utility endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/utility

## GET /v1/utility/endpoints
List every available endpoint
Credit cost: Free (0 credits)
Parameters:
- platform (optional, string): Filter the catalog to a single platform slug (e.g. tiktok)
- search (optional, string): Keyword search over endpoint paths, summaries, parameter names and descriptions, and tags, best match first (data.ranking says keyword)
- method (optional, enum: GET | POST | PATCH | DELETE): Filter by HTTP method (GET, POST, PATCH or DELETE)
- fingerprint (optional, boolean): Set to 1 to return only the registry fingerprint (a hash of every endpoint's params, prices and contract facts) and the platform and endpoint counts, to check whether a bundled copy of the catalog is current
curl "https://www.socialcrawl.dev/v1/utility/endpoints" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/endpoint
How to use any endpoint
Credit cost: Free (0 credits)
Parameters:
- id (optional, string): Endpoint id as platform/resource, e.g. tiktok/profile
- url (optional, string): Endpoint path form, e.g. /v1/tiktok/profile (a full https URL also works)
- method (optional, enum: GET | POST | PATCH | DELETE): Disambiguates a resource registered under more than one HTTP method, e.g. /v1/web/monitors/{monitor_id} is GET, PATCH and DELETE. Omit it and the first registered method wins
- Constraint: one of id, url (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/endpoint" \
  --data-urlencode "id=tiktok/profile" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/capabilities
List the parameters that work across endpoints
Credit cost: Free (0 credits)
Parameters:
- param (optional, string): Return one capability only, by parameter name (for example label or relevance)
curl "https://www.socialcrawl.dev/v1/utility/capabilities" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/plan
Plan the calls for a job
Credit cost: Free (0 credits)
Parameters:
- query (optional, string): The job in plain words, in any language. Up to 600 characters are read. Provide this or task
- task (optional, string): Alias for query (utility/find's name). Provide this or query
- Constraint: one of query, task (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/plan" \
  --data-urlencode "query=Combine @acme's TikTok profile with their recent videos and the comments on them" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/resolve
Identify a URL, handle or id
Credit cost: Free (0 credits)
Parameters:
- input (optional, string): One URL, @handle, platform:handle or id. Provide this or inputs, not both
- inputs (optional, string): Up to 100 values separated by commas or newlines, answered in order. Provide this or input, not both
- Constraint: one of input, inputs (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/resolve" \
  --data-urlencode "input=https://www.tiktok.com/@charlidamelio/video/7694438544479128845" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/estimate
Quote the credit cost of a call or a plan
Credit cost: Free (0 credits)
Parameters:
- id (optional, string): The endpoint to price, as platform/resource (tiktok/post/comments) or its /v1 path, optionally with its query string. Provide this or plan
- method (optional, enum: GET | POST | PATCH | DELETE): HTTP method, when the endpoint takes more than one. Defaults to GET when offered
- params (optional, string): The endpoint's own params, as a URL-encoded query string (url=...&label=spam) or a JSON object. Optional: they may also be sent directly on this URL; these win on a conflict
- body (optional, string): A batch endpoint's JSON body, as JSON or base64url JSON (for example {"urls":[...]} for prism/post-stats)
- items (optional, integer): Rows you want. Converted to pages with the endpoint's verified page size; warns pages_unknown when it has none
- plan (optional, string): Several calls at once, as base64url JSON (or JSON): {calls:[{id, params, repeat?, items?}], fan_out?:[{from, each, to}]}, or a utility/plan answer's steps. Provide this or id
- Constraint: one of id, plan (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/estimate" \
  --data-urlencode "id=tiktok/post/comments" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/explain-error
Explain a failed API response
Credit cost: Free (0 credits)
Parameters:
- status (optional, integer): The HTTP status of the failed response. Optional when the body carries error.status
- body (optional, string): The pasted response body: the JSON error envelope (URL-encoded or base64url) or plain text. Up to 8,000 characters. Provide this or status
- request (optional, string): The request that failed, as a URL or /v1 path with its query string. Lets the answer return a corrected request. Credentials in it are dropped
- Constraint: one of body, status (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/explain-error" \
  --data-urlencode "body={\"success\":false,\"error\":{\"type\":\"INVALID_REQUEST\",\"message\":\"Unknown query parameter 'handel'. Did you mean 'handle'?\",\"status\":400,\"details\":{\"unknown_parameters\":[\"handel\"],\"suggestions\":{\"handel\":\"handle\"}}}}" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/ai-detection
Check how likely a text was written by AI
Credit cost: 1 credit per text. A call that cannot be scored right now (503) is not charged.
Parameters:
- text (required): The text to check: a post, comment or passage, up to 8000 characters (URL-encode it)
curl -G "https://www.socialcrawl.dev/v1/utility/ai-detection" \
  --data-urlencode "text=I asked my AI employee for a summary of our feedback pile. He came back with a page our standup now opens on." \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/docs-search
Search the docs
Credit cost: Free (0 credits)
Parameters:
- query (optional, string): What to look up, in a few words or a question. Provide this or q
- q (optional, string): Short alias for query. Provide this or query
- platform (optional, string): Scope the search to one platform slug
- limit (optional, integer): Sections to return, 1 to 10 (default 5)
- Constraint: one of query, q (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/docs-search" \
  --data-urlencode "query=how does cursor pagination work" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/find
Find the endpoint for a task
Credit cost: Free (0 credits)
Parameters:
- task (optional, string): The job in plain words, in any language. Up to 600 characters are read. Provide this or query
- query (optional, string): Alias for task. Provide this or task
- platform (optional, string): Keep the answer on one platform slug (tiktok, instagram, ...). Omit to search every platform
- Constraint: one of task, query (at least one required)
curl -G "https://www.socialcrawl.dev/v1/utility/find" \
  --data-urlencode "task=last 200 comments on https://www.tiktok.com/@stoolpresidente/video/7623818255903329566" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/recipes
List task recipes with their cost
Credit cost: Free (0 credits)
Parameters:
- id (optional, string): One recipe id (export-tiktok-comments), which adds its runnable code. Omit for the whole catalog
curl "https://www.socialcrawl.dev/v1/utility/recipes" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/quickstart
Get started in one call
Credit cost: Free (0 credits)
Parameters:
- platform (optional, string): Tailor the first-call example and links to one platform slug
curl "https://www.socialcrawl.dev/v1/utility/quickstart" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/utility/llms
AI-agent context payload
Credit cost: Free (0 credits)
Parameters:
- platform (optional, string): Scope the context to one platform slug
- format (optional, enum: markdown | json): markdown (default) returns the llms corpus text; json returns a structured context object
curl "https://www.socialcrawl.dev/v1/utility/llms" \
  -H "x-api-key: YOUR_API_KEY"