API

Sift exposes a REST API at https://api.getsift.ai. Use it to read actions, agents, queues, conversations, and analytics. You can also set custom fields, submit moderation cases, and ingest normalized records.

At a glance

Authentication

Every request must include your API key in the X-API-Key header:

GET /v0/action/list
X-API-Key: sk_live_your_key_here

See the API Keys page for how to generate and manage keys, and what a key can and can't do.

Exploring the API

Sift publishes a full OpenAPI spec and an interactive Swagger UI:

• OpenAPI JSON: https://api.getsift.ai/docs/json
• Swagger UI: https://api.getsift.ai/docs

You can import the OpenAPI spec into Postman, Insomnia, or any API client.

First request for an agent

Read the API field reference before building a request. Use the OpenAPI JSON for complete machine-readable schemas.

curl --get 'https://api.getsift.ai/v0/action/list' \
  --header "X-API-Key: $SIFT_API_KEY" \
  --data-urlencode 'fullFilter=src=TWITTER+st=OPEN' \
  --data-urlencode 'from=2026-10-01T00:00:00Z' \
  --data-urlencode 'to=2026-10-07T23:59:59Z' \
  --data-urlencode 'pageSize=20'

SIFT_API_KEY is an environment variable, not a literal key in the example. fullFilter applies all conditions and adds no responded default. Legacy filter and filterJson read only the responded flag. Do not use them for platform or queue filtering.

Inspect this endpoint's data array. Other REST endpoints use their own response envelopes. For reliable cursor walks and dependent agent calls, use MCP.

Endpoints

There is no endpoint that sends or posts a reply on a customer's behalf - the write routes cover custom fields, moderation submissions, normalized ingestion, and Custom API.

Moderation intake

Moderation endpoints are available only when your organization is configured for Sift's ad_policy moderation mode. Intake validates the complete request before enqueueing work into the normal Sift ingestion and synthesis pipeline.

The externalId is immutable within your organization. Retrying the exact same submission returns duplicate. Reusing an existing externalId with different known content returns 409 for the single-case endpoint. In batch, every input receives an ordered accepted, duplicate, or rejected result; a conflicting item is rejected without preventing other valid items from being accepted.

Use the returned caseId with the GET endpoint. Polling returns only the evaluation for the currently active policy workflow and never falls back to an older completed evaluation. A case may report policy_not_configured, pending, running, completed, or failed. The final decision is included only after completion.

Custom API intake

Use Custom API to import customer content from your own tools. Create a source under Integrations, then create an Import key for its selected sources. Intake requires ingest; receipt reads require ingest:read. Reporting and general Write keys do not grant these scopes.

The guide includes single-item and batch imports, validation, receipt tracking, threading, and corrections.

Error Format

Errors return a consistent JSON body:

{
  "success": false,
  "error": "Action not found"
}

Some endpoints add extra fields on specific error cases - for example, the custom-fields PATCH returns a fieldErrors object (field name → message) on a 422. An uncaught server error always returns 500 with { "success": false, "error": "Internal server error" }.

Common status codes: 400 (bad request), 401 (missing or invalid key), 403 (forbidden, e.g. a read-scoped key calling a write route), 404 (not found), 409 (immutable identifier conflict), 422 (validation failed), 500 (server error).

Versioning

The current API version is v0. Breaking changes will be introduced under a new version prefix; non-breaking additions (new fields, new endpoints) can be added at any time without a version bump.

Related