# Changelog Docs Every change to the API, newest first. Also a [JSON Feed](https://staging.socialtap.dev/changelog.json). Changes within `/v1` are additive: anything that would break a client is announced here first, with a sunset date. ## Self-serve signup, test keys, API key management and usage 2026-10-26 · Added You can now get started without talking to anyone, test for free, and manage your account through the API. - **Sign up** with your email address: the emailed link creates your account with free credits, a live key and a test key, and opens the dashboard (keys, usage, balance, credit packs). **AI agents** can sign up with `POST /v1/agent_signup`: they get a test key at once and a live key that works once you confirm by email. - **Test keys** (`st_test_…`) answer every endpoint from recorded responses, free and deterministic, and reserved "magic" inputs trigger each error code, so integrations and CI can exercise every branch at no cost. - **API keys** have scopes (`endpoints`, `jobs`, `account:read`, `admin`), optional spend limits per day or month (`spend_limit_reached`), expiry and IP allowlists, managed through `/v1/api_keys`. - **Account and usage**: `GET /v1/account` (balance, plan, the calling key), `GET /v1/usage` (requests and credits over time by endpoint, key and outcome) and `GET /v1/credit_transactions` (the ledger). Set `low_balance_threshold` to get a `credits.low` email and event. - `meta.mode` says whether a response came from a live or a test key. `forbidden` is now returned (with `details.reason`), and a missing key's `unauthorized` says where to get one. **Contract changes (104)** - `endpoint facebook.transcript: accepts video links` - `endpoint instagram.transcript: accepts video links` - `endpoint instagram.transcript: accepts post links` - `endpoint tiktok.transcript: accepts video links` - `endpoint tiktok.transcript: accepts post links` - `endpoint youtube.transcript: accepts video links` - `error code endpoint_retired added (HTTP 410)` - `error code forbidden added (HTTP 403)` - `error code idempotency_key_in_progress added (HTTP 409)` - `error code idempotency_key_reused added (HTTP 422)` - `error code insufficient_credits: details key credits_required added` - `error code insufficient_credits: details key credits_available added` - `error code invalid_cursor: details key reason added` - `error code invalid_input: details key suggestion added` - `error code invalid_input: details key accepted_params added` - `error code invalid_input: details key url_kind added` - `error code invalid_input: details key url_platform added` - `error code invalid_input: details key accepted_url_kinds added` - `error code invalid_input: details key endpoints added` - `error code invalid_input: details key fields added` - `error code job_not_found added (HTTP 404)` - `error code overloaded: details key retry_after added` - `error code rate_limited: details key retry_after added` - `error code spend_limit_reached added (HTTP 402)` - `header cache-control added` - `header deprecation added` - `header link added` - `header ratelimit added` - `header ratelimit-policy added` - `header sunset added` - `header traceparent added` - `header x-client-request-id added` - `common param fields added` - `warning code deprecated_endpoint added` - `shared param country added` - `shared param lang added` - `shared param since added` - `shared param sort added` - `shared param until added` - `meta fields are part of the locked contract` - `page fields are part of the locked contract` - `error fields are part of the locked contract` - `MCP tool find_endpoint added` - `MCP tool get_transcript added` - `header authorization added` - `error code forbidden: details key reason added` - `error code forbidden: details key required_scope added` - `error code spend_limit_reached: details key api_key_id added` - `error code spend_limit_reached: details key spend_limit added` - `error code spend_limit_reached: details key interval added` - `error code spend_limit_reached: details key used added` - `error code spend_limit_reached: details key credits_required added` - `error code spend_limit_reached: details key resets_at added` - `error code unauthorized: details key signup_url added` - `error code unauthorized: details key agent_signup_url added` - `meta: field mode added` - `MCP tool get_account added` - `error code insufficient_credits: details key max_credits added` - `header idempotency-key added` - `header idempotent-replayed added` - `header location added` - `header prefer added` - `header preference-applied added` - `header webhook-id added` - `header webhook-signature added` - `header webhook-timestamp added` - `event type job.completed added` - `event type job.canceled added` - `event type job.expired added` - `event type credits.low added` - `event type credits.depleted added` - `event type api_key.spend_limit_reached added` - `event type webhook.test added` - `operation DELETE /v1/webhook_endpoints/{id} added (webhook_endpoints.delete)` - `operation GET /v1/events added (events.list)` - `operation GET /v1/events/{id} added (events.get)` - `operation GET /v1/jobs added (jobs.list)` - `operation GET /v1/jobs/{id} added (jobs.get)` - `operation GET /v1/jobs/{id}/results added (jobs.results.list)` - `operation GET /v1/jobs/{id}/results.jsonl added (jobs.results.download)` - `operation GET /v1/webhook_endpoints added (webhook_endpoints.list)` - `operation GET /v1/webhook_endpoints/{id} added (webhook_endpoints.get)` - `operation GET /v1/webhook_endpoints/{id}/deliveries added (webhook_endpoints.deliveries.list)` - `operation PATCH /v1/webhook_endpoints/{id} added (webhook_endpoints.update)` - `operation POST /v1/events/{id}/redeliver added (events.redeliver)` - `operation POST /v1/jobs added (jobs.create)` - `operation POST /v1/jobs/{id}/cancel added (jobs.cancel)` - `operation POST /v1/webhook_endpoints added (webhook_endpoints.create)` - `operation POST /v1/webhook_endpoints/{id}/rotate_secret added (webhook_endpoints.rotate_secret)` - `operation POST /v1/webhook_endpoints/{id}/test added (webhook_endpoints.test)` - `MCP tool create_job added` - `MCP tool get_job added` - `endpoint tiktok.profile added (/v1/tiktok/profile)` - `resource profile is live` - `MCP tool get_profile added` - `endpoint instagram.post added (/v1/instagram/post)` - `resource post is live` - `MCP tool get_post added` - `endpoint facebook.search_ads added (/v1/facebook/search_ads)` - `resource ad is live` - `MCP tool search added` - `endpoint youtube.comments added (/v1/youtube/comments)` - `resource comment is live` - `MCP tool list_comments added` ## Request conventions, richer errors and response metadata 2026-10-26 · Changed Every endpoint now follows the same request conventions, and every response tells you more about itself. - **Unknown parameters are rejected** with `invalid_input`, free, naming the parameter and the one you most likely meant (`username` → `handle`). Previously they were ignored. Common parameters (`max_age`, `fields`) are always known. - **Errors carry everything needed to react** without parsing the message: `status`, `retryable`, `param`, `remediation`, `doc_url`, `details` (for example `credits_required`, or the endpoint a link belongs to) and `charged` (always false). `retry-after` is never sent on credit errors. - **A link of the wrong kind** (a profile link sent to a video endpoint, a link from another platform) is answered with the endpoint that takes it. - **`meta`** gains `input` (what your url resolved to), `credits_remaining`, `client_request_id` and `warnings`. - **`fields`** selects only the fields you need, after the cache, at no cost. - **Lists** gain `page.end_reason` and a `Link: rel="next"` header; `since` stops paging on newest-first lists. - **Headers**: send `x-client-request-id` to have your own ID echoed and logged, and `traceparent` to match traces. `RateLimit-Policy` and `RateLimit` describe the account's runaway-protection ceiling, and `Cache-Control: max-age` works like `max_age`. - Deprecated endpoints will announce themselves with `Deprecation` and `Sunset` headers and a warning, and answer `endpoint_retired` after their sunset. This changelog is also a [JSON Feed](https://staging.socialtap.dev/changelog.json). ## Background jobs and batches, webhooks, events and Idempotency-Key 2026-10-26 · Added Run many requests, or one long one, without holding a connection open, and hear back when they are done. - **Jobs**: `POST /v1/jobs` runs a batch of endpoint requests in the background, at each endpoint's own price, and `max_pages` walks a whole list server-side. With `?wait` a short job answers inline (a synchronous batch); otherwise poll `GET /v1/jobs/{id}` (free), page through `GET /v1/jobs/{id}/results` as items finish, or download every result from the job's signed `results_url`. `Prefer: respond-async` turns any endpoint request into a one-request job. - **Credits** are set aside per job (`max_credits`) and charged per item as it ends; failed items are free. A key's spend limit holds through its jobs, and a test key's jobs answer from recorded responses, free. - **Webhooks** (Standard Webhooks signatures, retried for days, secrets rotated without downtime) deliver `job.completed`, `job.canceled`, `job.expired`, `credits.low`, `credits.depleted` and `api_key.spend_limit_reached`; `/v1/events` lists every event and redelivers one on request. - **Idempotency-Key** on every POST: retrying with the same key and body never repeats the work. - The SDKs gain `jobs`, `webhookEndpoints` and `events`, a create-and-wait helper and webhook signature verification. --- [HTML version](https://staging.socialtap.dev/docs/changelog/) · [Docs index for AI agents](https://staging.socialtap.dev/llms.txt) · [All docs in one file](https://staging.socialtap.dev/llms-full.txt)