# API field reference (/docs/developer/api-reference) Every REST endpoint below lists its query, path, body, and response fields. Read this with the [API guide](/docs/developer/api). ## At a glance [#at-a-glance] | Contract | Behavior | | --------------------------------------- | ------------------------------------------------ | | Authentication | `X-API-Key` header | | Base URL | `https://api.getsift.ai` | | Version | `v0` | | Full filtering on action list | `fullFilter` | | Conversation pagination | `page` and `pageSize` | | MCP pagination | Different contract; use `cursor` and `limit` | | Complete machine-readable REST contract | [OpenAPI JSON](https://api.getsift.ai/docs/json) | ## What you're looking at [#what-youre-looking-at] This reference follows the public OpenAPI contract retrieved on 2026-10-08. It covers each declared nested field. Required and optional labels apply inside the parent object. A child marked required does not make an optional parent mandatory. Nullable values represent missing or unavailable facts. Dynamic maps can contain organization-defined keys. Use the live OpenAPI contract for changes after this reference date. ## Filtering and pagination rules [#filtering-and-pagination-rules] `GET /v0/action/list` defaults to the past seven days and responded actions. Send `fullFilter` to apply the complete Operations DSL. It adds no responded default. Legacy `filter` and `filterJson` read only the responded flag. Do not rely on them for platform, queue, or status filtering. Do not combine `fullFilter` with either legacy field. The action list accepts no numbered `page` input. Its response includes page metadata, but that does not create a page parameter. Continue with timestamp windows and deduplicate by `actionId`. Equal timestamps can complicate large exports; use MCP cursor pagination for resumable record walks. The action list's `to` is inclusive. A date-only value is midnight UTC, not the end of that date. `sortBy` controls both the date filter and newest-first order. Supply explicit timestamps for precise windows. Conversation search accepts numbered `page` and `pageSize`. Inspect `totalRecordsCapped` before treating a reported count as exact. ## Endpoint fields [#endpoint-fields] ### `GET /v0/action/list` [#get-v0actionlist]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | | `pageSize` (query) | integer | Optional. Response page size. Default `50`. Minimum `1`. Maximum `500`. | | `filter` (query) | string | Optional. Endpoint-specific filter text. Read the filtering guide before using it. | | `filterJson` (query) | string | Optional. Legacy JSON filter text; only the responded flag applies. | | `fullFilter` (query) | string | Optional. Full Operations DSL filter. Do not combine with filter or filterJson. Maximum characters `10000`. | | `includeFullConversation` (query) | boolean | Optional. Include the serialized conversation. Default `false`. | | `sortBy` (query) | string | Optional. Choose createdAt or updatedAt for both filtering and newest-first ordering. Default `"createdAt"`. Values: `createdAt`, `updatedAt`. | **Response `200`** | Field | Type | Requirement and meaning | | ---------------------------- | --------------- | ------------------------------------------------------------------------ | | `data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data[].actionId` | string | Required. Sift action identifier. Keep it as a string. | | `data[].actionTitle` | string | Required. Action title. | | `data[].actionSummary` | string | Required. Sift summary of the action. | | `data[].status` | string | Required. Current state. Use the declared enum when present. | | `data[].platform` | string | Required. Source platform. | | `data[].recordType` | string / null | Required. Source record type. | | `data[].isPublicPost` | boolean | Required. Whether the record is public. | | `data[].siftURL` | string | Required. Link to the action in Sift. | | `data[].sourceURL` | string / null | Required. Link to the original record; can be null for private content. | | `data[].queue` | string / null | Required. Current queue label. | | `data[].initialQueue` | string / null | Required. Original queue label. | | `data[].sentiment` | string / null | Required. Sentiment label. | | `data[].sentimentScore` | number / null | Required. Stored sentiment score. | | `data[].moderation` | string / null | Required. Stored moderation value. | | `data[].assigneeName` | string / null | Required. Assigned agent name. | | `data[].assigneeEmail` | string / null | Required. Assigned agent email. | | `data[].assigneeUserId` | string / null | Required. Assigned agent identifier. | | `data[].assigneeRole` | string / null | Required. Assigned agent role. | | `data[].userName` | string | Required. Customer name. | | `data[].userUsername` | string | Required. Customer platform handle. | | `data[].userId` | string | Required. User identifier. Preserve its original string value. | | `data[].userEmail` | string / null | Required. Customer email. | | `data[].userFollowerCount` | number / null | Required. Stored customer follower count; null if unavailable. | | `data[].createdAt` | string | Required. Creation timestamp. | | `data[].updatedAt` | string / null | Required. Last update timestamp. | | `data[].initialMessageTime` | string / null | Required. Time of the first customer message. | | `data[].initialResponseTime` | string / null | Required. Time of the first agent response. | | `data[].closeTime` | string / null | Required. Time the action closed. | | `data[].claimTime` | string / null | Required. Time the action was claimed. | | `data[].firstResponseTime` | string / null | Required. Exported response duration value. Do not parse as a timestamp. | | `data[].handleTime` | string / null | Required. Exported handling duration value. Do not parse as a timestamp. | | `data[].serverName` | string | Required. Source account or community name. | | `data[].channelName` | string | Required. Source channel name. | | `data[].csatScore` | string / null | Required. Reported customer satisfaction score. | | `data[].csatFeedback` | string / null | Required. Customer satisfaction feedback. | | `data[].estimatedCSAT` | number / null | Required. Estimated satisfaction score. | | `data[].totalMessages` | number / null | Required. Message count. | | `data[].totalUserMessages` | number / null | Required. Customer message count. | | `data[].totalAgentMessages` | number / null | Required. Agent message count. | | `data[].tags` | array of object | Required. Action tags. | | `data[].tags[].value` | string | Required. Tag label. | | `data[].tags[].group` | string | Required. Tag group label. | | `data[].closingTags` | array of object | Required. Tags applied at closure. | | `data[].closingTags[].value` | string | Required. Tag label. | | `data[].closingTags[].group` | string | Required. Tag group label. | | `data[].customFields` | object | Required. Organization-defined field names and values. | | `data[].rootMessageText` | string / null | Required. Root message body. | | `data[].conversationJson` | string / null | Required. Serialized conversation JSON when requested; null otherwise. | | `totalRecords` | number | Required. Matching record count returned by this endpoint. | | `currentPage` | number | Required. Page represented by the response. | | `pageSize` | number | Required. Response page size. | | `totalPages` | number | Required. Number of reported pages. | **Response `400`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/action/{id}` [#get-v0actionid]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ----------- | ------ | ------------------------------------ | | `id` (path) | string | Required. Identifier of this object. | **Response `200`** | Field | Type | Requirement and meaning | | -------------------------------- | --------------- | ------------------------------------------------------------------------ | | `user` | object | Required. Customer profile. | | `user.name` | string | Required. Display name. | | `user.username` | string | Required. Platform handle. | | `user.userId` | string | Required. User identifier. Preserve its original string value. | | `user.email` | string / null | Required. Email address. | | `user.followerCount` | number / null | Required. Stored follower count; null if unavailable. | | `actionId` | string | Required. Sift action identifier. Keep it as a string. | | `actionTitle` | string | Required. Action title. | | `actionSummary` | string | Required. Sift summary of the action. | | `platform` | string | Required. Source platform. | | `recordType` | string / null | Required. Source record type. | | `isPublicPost` | boolean | Required. Whether the record is public. | | `sentiment` | string / null | Required. Sentiment label. | | `sentimentScore` | number / null | Required. Stored sentiment score. | | `queue` | string / null | Required. Current queue label. | | `initialQueue` | string / null | Required. Original queue label. | | `status` | string | Required. Current state. Use the declared enum when present. | | `createdAt` | string | Required. Creation timestamp. | | `siftURL` | string | Required. Link to the action in Sift. | | `sourceURL` | string / null | Required. Link to the original record; can be null for private content. | | `updatedAt` | string / null | Required. Last update timestamp. | | `initialMessageTime` | string / null | Required. Time of the first customer message. | | `initialResponseTime` | string / null | Required. Time of the first agent response. | | `closeTime` | string / null | Required. Time the action closed. | | `firstResponseTime` | string / null | Required. Exported response duration value. Do not parse as a timestamp. | | `handleTime` | string / null | Required. Exported handling duration value. Do not parse as a timestamp. | | `claimTime` | string / null | Required. Time the action was claimed. | | `assignee` | object | Required. Assigned Sift agent. | | `assignee.name` | string / null | Required. Display name. | | `assignee.email` | string / null | Required. Email address. | | `assignee.userId` | string / null | Required. User identifier. Preserve its original string value. | | `assignee.role` | string / null | Required. Role label. | | `serverName` | string | Required. Source account or community name. | | `channelName` | string | Required. Source channel name. | | `tags` | array of object | Required. Action tags. | | `tags[].value` | string | Required. Tag label. | | `tags[].group` | string | Required. Tag group label. | | `closingTags` | array of object | Required. Tags applied at closure. | | `closingTags[].value` | string | Required. Tag label. | | `closingTags[].group` | string | Required. Tag group label. | | `moderation` | string / null | Required. Stored moderation value. | | `comments` | array of object | Required. Exported comments. | | `comments[].text` | string | Required. Text body. | | `comments[].authorNativeId` | string | Required. Platform-native author ID. | | `comments[].authorNativeName` | string / null | Required. Platform-native author name. | | `messages` | array of object | Required. Exported message records. | | `messages[].id` | string | Required. Identifier of this object. | | `messages[].timestamp` | string | Required. Message or event timestamp. | | `messages[].author` | string | Required. Author name. | | `messages[].authorId` | string | Optional. Author identifier. | | `messages[].authorType` | string | Required. USER, AGENT, or BOT. Values: `USER`, `AGENT`, `BOT`. | | `messages[].message` | string | Required. Message body. | | `messages[].mediaUrls` | array of string | Required. Media links. | | `rootMessageText` | string / null | Required. Root message body. | | `conversation` | array of object | Optional. Optional full conversation. | | `conversation[].id` | string | Required. Identifier of this object. | | `conversation[].timestamp` | string | Required. Message or event timestamp. | | `conversation[].author` | string | Required. Author name. | | `conversation[].authorId` | string / null | Required. Author identifier. | | `conversation[].authorType` | string | Required. USER, AGENT, or BOT. Values: `USER`, `AGENT`, `BOT`. | | `conversation[].message` | string | Required. Message body. | | `conversation[].parentMessageId` | string / null | Required. Parent message identifier; null if unavailable. | | `conversation[].mediaUrls` | array of string | Required. Media links. | | `customFields` | object | Required. Organization-defined field names and values. | | `csatScore` | string / null | Required. Reported customer satisfaction score. | | `csatFeedback` | string / null | Required. Customer satisfaction feedback. | | `estimatedCSAT` | number / null | Required. Estimated satisfaction score. | | `totalMessages` | number / null | Required. Message count. | | `totalUserMessages` | number / null | Required. Customer message count. | | `totalAgentMessages` | number / null | Required. Agent message count. | **Response `404`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `PATCH /v0/actions/{actionId}/custom-fields` [#patch-v0actionsactionidcustom-fields]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ----------------- | ------ | ------------------------------------------------------------------------------ | | `actionId` (path) | string | Required. Sift action identifier. Keep it as a string. Minimum characters `1`. | **JSON body** | Field | Type | Requirement and meaning | | --------------------- | --------------- | ----------------------------------------------------------------------- | | `fields` | array of object | Required. Custom fields in this request or response. Minimum items `1`. | | `fields[].fieldName` | string | Required. Registered custom field name. Minimum characters `1`. | | `fields[].value` | JSON | Required. Field value. Its accepted type depends on the declared field. | | `fields[].confidence` | number | Optional. Optional confidence from 0 to 1. Minimum `0`. Maximum `1`. | | `fields[].rationale` | string | Optional. Optional reason for the field value. | **Response `200`** | Field | Type | Requirement and meaning | | --------------------- | --------------- | ----------------------------------------------------------------------- | | `actionId` | string | Required. Sift action identifier. Keep it as a string. | | `updated` | array of object | Required. Fields that this request updates. | | `updated[].fieldName` | string | Required. Registered custom field name. | | `updated[].value` | JSON | Required. Field value. Its accepted type depends on the declared field. | **Response `403`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. | **Response `404`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. | **Response `422`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. | **Response `500`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. |
### `GET /v0/actions/{actionId}/custom-fields` [#get-v0actionsactionidcustom-fields]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ----------------- | ------ | ------------------------------------------------------------------------------ | | `actionId` (path) | string | Required. Sift action identifier. Keep it as a string. Minimum characters `1`. | **Response `200`** | Field | Type | Requirement and meaning | | ---------------------- | --------------- | ----------------------------------------------------------------------- | | `actionId` | string | Required. Sift action identifier. Keep it as a string. | | `fields` | array of object | Required. Custom fields in this request or response. | | `fields[].fieldName` | string | Required. Registered custom field name. | | `fields[].displayName` | string | Required. Customer-visible field label. | | `fields[].fieldType` | string | Required. Registered field type. | | `fields[].value` | JSON | Required. Field value. Its accepted type depends on the declared field. | | `fields[].provenance` | JSON | Optional. Stored origin of the value. | **Response `403`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. | **Response `404`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. | **Response `500`** | Field | Type | Requirement and meaning | | ------------- | ------- | ----------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | | `fieldErrors` | object | Optional. Field name to validation message map. |
### `GET /v0/agents` [#get-v0agents]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | -------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | **Response `200`** | Field | Type | Requirement and meaning | | ----------------------------------------- | --------------- | ----------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data[].agentId` | string | Required. Sift agent identifier. | | `data[].metrics` | object | Required. Metrics for the selected window. | | `data[].metrics.totalActions` | number | Required. Action count. | | `data[].metrics.totalActionsWithResponse` | number | Required. Actions with an agent response. | | `data[].metrics.totalMessages` | number | Required. Message count. | | `data[].metrics.totalAgentMessages` | number | Required. Agent message count. | | `data[].metrics.totalUserMessages` | number | Required. Customer message count. | | `data[].metrics.averageCsat` | number | Required. Average reported satisfaction. | | `data[].metrics.averageResponseTime` | number | Required. Average response time. Check the metrics reference for units. | | `data[].metrics.averageHandleTime` | number | Required. Average handling time. Check the metrics reference for units. | | `data[].metrics.averageEstimatedCsat` | number | Required. Average estimated satisfaction. | | `data[].metrics.averageResolutionQuality` | number | Required. Average resolution quality. | | `data[].metrics.averageSentimentChange` | number | Required. Average sentiment change. | | `data[].metrics.averageRubricScore` | number | Required. Average rubric score. | | `data[].workload` | object | Required. Counts by workload state. | | `data[].workload.active` | number | Required. Active action count. | | `data[].workload.closed` | number | Required. Closed action count. | | `data[].workload.cancelled` | number | Required. Cancelled action count. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/agents/{id}` [#get-v0agentsid]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | -------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | | `id` (path) | string | Required. Identifier of this object. | **Response `200`** | Field | Type | Requirement and meaning | | ------------------------------------------------- | --------------- | ----------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `data` | object | Required. Result data. Read the nested contract for this endpoint. | | `data.metrics` | array of object | Required. Metrics for the selected window. | | `data.aggregatedMetrics` | object | Required. Aggregated agent metrics. | | `data.aggregatedMetrics.totalActions` | number | Required. Action count. | | `data.aggregatedMetrics.totalMessages` | number | Required. Message count. | | `data.aggregatedMetrics.totalAgentMessages` | number | Required. Agent message count. | | `data.aggregatedMetrics.totalUserMessages` | number | Required. Customer message count. | | `data.aggregatedMetrics.averageCsat` | number | Required. Average reported satisfaction. | | `data.aggregatedMetrics.averageResponseTime` | number | Required. Average response time. Check the metrics reference for units. | | `data.aggregatedMetrics.averageHandleTime` | number | Required. Average handling time. Check the metrics reference for units. | | `data.aggregatedMetrics.averageEstimatedCsat` | number | Required. Average estimated satisfaction. | | `data.aggregatedMetrics.averageResolutionQuality` | number | Required. Average resolution quality. | | `data.aggregatedMetrics.averageSentimentChange` | number | Required. Average sentiment change. | | `data.aggregatedMetrics.averageRubricScore` | number | Required. Average rubric score. | | `data.currentWorkload` | object | Required. Current agent workload. | | `data.currentWorkload.active` | number | Required. Active action count. | | `data.currentWorkload.closed` | number | Required. Closed action count. | | `data.currentWorkload.cancelled` | number | Required. Cancelled action count. | | `data.queues` | array of object | Required. Agent queue records. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `404`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/queues` [#get-v0queues]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | -------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | **Response `200`** | Field | Type | Requirement and meaning | | ----------------------------------------- | --------------- | ----------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data[].queueId` | string / null | Required. Queue identifier; null can represent no queue. | | `data[].queueName` | string / null | Required. Queue name. | | `data[].metrics` | object | Required. Metrics for the selected window. | | `data[].metrics.totalActions` | number | Required. Action count. | | `data[].metrics.totalMessages` | number | Required. Message count. | | `data[].metrics.totalAgentMessages` | number | Required. Agent message count. | | `data[].metrics.totalUserMessages` | number | Required. Customer message count. | | `data[].metrics.averageCsat` | number | Required. Average reported satisfaction. | | `data[].metrics.averageResponseTime` | number | Required. Average response time. Check the metrics reference for units. | | `data[].metrics.averageHandleTime` | number | Required. Average handling time. Check the metrics reference for units. | | `data[].metrics.averageEstimatedCsat` | number | Required. Average estimated satisfaction. | | `data[].metrics.averageResolutionQuality` | number | Required. Average resolution quality. | | `data[].metrics.averageSentimentChange` | number | Required. Average sentiment change. | | `data[].metrics.averageRubricScore` | number | Required. Average rubric score. | | `data[].metrics.averageSentimentScore` | number | Required. Average sentiment score. | | `data[].workload` | object | Required. Counts by workload state. | | `data[].workload.active` | number | Required. Active action count. | | `data[].workload.closed` | number | Required. Closed action count. | | `data[].workload.cancelled` | number | Required. Cancelled action count. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/analytics/tags` [#get-v0analyticstags]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ----------------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | | `respondedOnly` (query) | boolean | Optional. Restrict tag analytics to responded records when enabled. | | `limit` (query) | number | Optional. Requested maximum result size. | | `offset` (query) | number | Optional. Starting result offset. | | `search` (query) | string | Optional. Text search over tags. | **Response `200`** | Field | Type | Requirement and meaning | | ------------------------------------- | --------------- | ------------------------------------------------------------------ | | `success` | boolean | Required. Whether the request succeeds. | | `data` | object | Required. Result data. Read the nested contract for this endpoint. | | `data.summary` | object | Required. Summary of the selected data. | | `data.summary.totalTags` | number | Required. Tag count. | | `data.summary.totalTagGroups` | number | Required. Tag group count. | | `data.summary.totalTaggedRecords` | number | Required. Tagged record count. | | `data.summary.totalActions` | number | Required. Action count. | | `data.tagBreakdown` | array of object | Required. Tag distribution. | | `data.tagBreakdown[].tagId` | string | Required. Tag identifier. | | `data.tagBreakdown[].tagName` | string | Required. Tag label. | | `data.tagBreakdown[].groupName` | string / null | Required. Tag group label. | | `data.tagBreakdown[].count` | number | Required. Count for this group. | | `data.tagBreakdown[].percentage` | number | Required. Percentage for this group. | | `data.volumeByTag` | array of object | Required. Volume and scores for each tag. | | `data.volumeByTag[].tagId` | string | Required. Tag identifier. | | `data.volumeByTag[].tagName` | string | Required. Tag label. | | `data.volumeByTag[].total` | number | Required. Total for this scope. | | `data.volumeByTag[].responded` | number | Required. Responded count. | | `data.volumeByTag[].notResponded` | number | Required. Unresponded count. | | `data.volumeByTag[].avgSentiment` | number / null | Required. Average sentiment. | | `data.volumeByTag[].avgActionability` | number / null | Required. Average actionability. | | `data.volumeByTag[].avgRelevance` | number / null | Required. Average relevance. | | `data.pagination` | object | Required. Pagination receipt. | | `data.pagination.total` | number | Required. Total for this scope. | | `data.pagination.limit` | number | Required. Requested maximum result size. | | `data.pagination.offset` | number | Required. Starting result offset. | | `data.pagination.hasMore` | boolean | Required. Whether another page exists. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/analytics/tags/volume` [#get-v0analyticstagsvolume]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ----------------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | | `respondedOnly` (query) | boolean | Optional. Restrict tag analytics to responded records when enabled. | | `topTagsLimit` (query) | number | Optional. Maximum number of top tags. | | `tagIds` (query) | string | Optional. Comma-separated tag IDs. | **Response `200`** | Field | Type | Requirement and meaning | | ----------- | --------------- | ------------------------------------------------------------------ | | `success` | boolean | Required. Whether the request succeeds. | | `data` | object | Required. Result data. Read the nested contract for this endpoint. | | `data.data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data.tags` | array of string | Required. Action tags. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/analytics/sentiment` [#get-v0analyticssentiment]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | -------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | **Response `200`** | Field | Type | Requirement and meaning | | ---------------------- | --------------- | ------------------------------------------------------------------ | | `success` | boolean | Required. Whether the request succeeds. | | `data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data[].day` | string | Required. Day bucket. | | `data[].Very Negative` | number | Required. Very negative sentiment count. | | `data[].Negative` | number | Required. Negative sentiment count. | | `data[].Neutral` | number | Required. Neutral sentiment count. | | `data[].Positive` | number | Required. Positive sentiment count. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/analytics/sentiment/by-tag` [#get-v0analyticssentimentby-tag]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | -------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | **Response `200`** | Field | Type | Requirement and meaning | | ---------------------- | --------------- | ------------------------------------------------------------------ | | `success` | boolean | Required. Whether the request succeeds. | | `data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data[].tagName` | string | Required. Tag label. | | `data[].veryNegative` | number | Required. Very negative sentiment count. | | `data[].negative` | number | Required. Negative sentiment count. | | `data[].neutral` | number | Required. Neutral sentiment count. | | `data[].positive` | number | Required. Positive sentiment count. | | `data[].totalMentions` | number | Required. Mentions counted for this tag. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/analytics/engagement` [#get-v0analyticsengagement]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ------------------- | ----------- | --------------------------------------------------------------------------------------------- | | `from` (query) | date string | Optional. ISO 8601 date or timestamp for the window start. A date-only value is midnight UTC. | | `to` (query) | date string | Optional. ISO 8601 date or timestamp for the window end. Check the endpoint date rules. | | `platforms` (query) | string | Optional. Comma-separated source platform values. | **Response `200`** | Field | Type | Requirement and meaning | | ---------------------------------------------------- | --------------- | ------------------------------------------------------------------ | | `success` | boolean | Required. Whether the request succeeds. | | `data` | object | Required. Result data. Read the nested contract for this endpoint. | | `data.engagementPercentiles` | array of object | Required. Message volume percentiles per platform. | | `data.engagementPercentiles[].platform` | string | Required. Source platform. | | `data.engagementPercentiles[].p25MessagesPerUser` | number | Required. 25th percentile of messages per user. | | `data.engagementPercentiles[].medianMessagesPerUser` | number | Required. Median messages per user. | | `data.engagementPercentiles[].p75MessagesPerUser` | number | Required. 75th percentile of messages per user. | | `data.growthTrends` | array of object | Required. Weekly user growth by platform. | | `data.growthTrends[].week` | string | Required. Week bucket. Format `date-time`. | | `data.growthTrends[].platform` | string | Required. Source platform. | | `data.growthTrends[].currentWeekUsers` | number | Required. Current week user count. | | `data.growthTrends[].previousWeekUsers` | number | Required. Previous week user count. | | `data.growthTrends[].growthPercentage` | number | Required. Growth percentage. | | `data.conversionFunnel` | array of object | Required. Source-defined funnel rows. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `GET /v0/conversations/search` [#get-v0conversationssearch]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | ------------------ | ------- | ---------------------------------------------------------------------------------- | | `filter` (query) | string | Optional. Endpoint-specific filter text. Read the filtering guide before using it. | | `page` (query) | integer | Optional. Numbered page, starting at 1. Default `1`. Minimum `1`. Maximum `10000`. | | `pageSize` (query) | integer | Optional. Response page size. Default `50`. Minimum `1`. Maximum `100`. | **Response `200`** | Field | Type | Requirement and meaning | | ---------------------------- | --------------- | --------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `data` | array of object | Required. Result data. Read the nested contract for this endpoint. | | `data[].actionId` | string | Required. Sift action identifier. Keep it as a string. | | `data[].actionTitle` | string | Required. Action title. | | `data[].actionSummary` | string | Required. Sift summary of the action. | | `data[].status` | string | Required. Current state. Use the declared enum when present. | | `data[].platform` | string | Required. Source platform. | | `data[].recordType` | string / null | Required. Source record type. | | `data[].isPublicPost` | boolean | Required. Whether the record is public. | | `data[].siftURL` | string | Required. Link to the action in Sift. | | `data[].sourceURL` | string / null | Required. Link to the original record; can be null for private content. | | `data[].queue` | string / null | Required. Current queue label. | | `data[].initialQueue` | string / null | Required. Original queue label. | | `data[].sentiment` | string / null | Required. Sentiment label. | | `data[].sentimentScore` | number / null | Required. Stored sentiment score. | | `data[].moderation` | string / null | Required. Stored moderation value. | | `data[].assigneeName` | string / null | Required. Assigned agent name. | | `data[].assigneeEmail` | string / null | Required. Assigned agent email. | | `data[].assigneeUserId` | string / null | Required. Assigned agent identifier. | | `data[].assigneeRole` | string / null | Required. Assigned agent role. | | `data[].userName` | string | Required. Customer name. | | `data[].userUsername` | string | Required. Customer platform handle. | | `data[].userId` | string | Required. User identifier. Preserve its original string value. | | `data[].userEmail` | string / null | Required. Customer email. | | `data[].userFollowerCount` | number / null | Required. Stored customer follower count; null if unavailable. | | `data[].createdAt` | string | Required. Creation timestamp. | | `data[].updatedAt` | string / null | Required. Last update timestamp. | | `data[].initialMessageTime` | string / null | Required. Time of the first customer message. | | `data[].initialResponseTime` | string / null | Required. Time of the first agent response. | | `data[].closeTime` | string / null | Required. Time the action closed. | | `data[].claimTime` | string / null | Required. Time the action was claimed. | | `data[].firstResponseTime` | string / null | Required. Exported response duration value. Do not parse as a timestamp. | | `data[].handleTime` | string / null | Required. Exported handling duration value. Do not parse as a timestamp. | | `data[].serverName` | string | Required. Source account or community name. | | `data[].channelName` | string | Required. Source channel name. | | `data[].csatScore` | string / null | Required. Reported customer satisfaction score. | | `data[].csatFeedback` | string / null | Required. Customer satisfaction feedback. | | `data[].estimatedCSAT` | number / null | Required. Estimated satisfaction score. | | `data[].totalMessages` | number / null | Required. Message count. | | `data[].totalUserMessages` | number / null | Required. Customer message count. | | `data[].totalAgentMessages` | number / null | Required. Agent message count. | | `data[].tags` | array of object | Required. Action tags. | | `data[].tags[].value` | string | Required. Tag label. | | `data[].tags[].group` | string | Required. Tag group label. | | `data[].closingTags` | array of object | Required. Tags applied at closure. | | `data[].closingTags[].value` | string | Required. Tag label. | | `data[].closingTags[].group` | string | Required. Tag group label. | | `data[].customFields` | object | Required. Organization-defined field names and values. | | `data[].rootMessageText` | string / null | Required. Root message body. | | `data[].conversationJson` | string / null | Required. Serialized conversation JSON when requested; null otherwise. | | `data[].threadId` | string | Required. Thread identifier. | | `data[].easyId` | string / null | Required. Readable case identifier. | | `data[].contributors` | string / null | Required. Stored contributor summary. | | `totalRecords` | number | Required. Matching record count returned by this endpoint. | | `totalRecordsCapped` | boolean | Required. Whether the count stops at a cap. Do not treat a capped count as exact. | | `currentPage` | number | Required. Page represented by the response. | | `pageSize` | number | Required. Response page size. | | `totalPages` | number | Required. Number of reported pages. | **Response `400`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | --------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. | | `error` | string | Required. Error message. |
### `POST /v0/moderation/cases` [#post-v0moderationcases]
Request and response fields **JSON body** | Field | Type | Requirement and meaning | | --------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `externalId` | string | Required. Producer identifier. Preserve it across exact retries. Minimum characters `1`. Maximum characters `256`. | | `sourceSystem` | string | Required. Producer system name. Minimum characters `1`. Maximum characters `128`. | | `sourcePlatform` | string | Required. Source advertising platform. Minimum characters `1`. Maximum characters `128`. | | `sourceAdId` | string | Required. Source ad identifier. Minimum characters `1`. Maximum characters `256`. | | `advertiserId` | string | Optional. Identifier of the advertiser. Minimum characters `1`. Maximum characters `256`. | | `advertiserName` | string | Required. Name of the advertiser. Minimum characters `1`. Maximum characters `500`. | | `campaignId` | string | Optional. Identifier of the campaign. Minimum characters `1`. Maximum characters `256`. | | `market` | string | Required. Market for policy evaluation. Minimum characters `1`. Maximum characters `128`. | | `placement` | string | Required. Ad placement. Minimum characters `1`. Maximum characters `128`. | | `language` | string | Optional. Language of the submitted content. Default `"en"`. Minimum characters `1`. Maximum characters `64`. | | `providerMetadata` | object | Optional. Provider metadata retained with the submission. | | `landingPageUrl` | string / null | Required. Landing page URL. | | `title` | string | Required. Record title. Minimum characters `1`. Maximum characters `500`. | | `headline` | string | Optional. Ad headline. Minimum characters `1`. Maximum characters `500`. | | `brandName` | string | Optional. Advertised brand name. Minimum characters `1`. Maximum characters `500`. | | `callToAction` | string | Optional. Call-to-action value. Values: `APPLY_NOW`, `BOOK_NOW`, `GET_NOW`, `INSTALL_NOW`, `MORE`, `SHOP_NOW`, `SIGN_UP`, `VIEW`, `WATCH`. | | `publicProfile` | object | Optional. Public profile information. | | `publicProfile.displayName` | string | Optional. Customer-visible field label. Minimum characters `1`. Maximum characters `500`. | | `publicProfile.logoUrl` | string | Optional. Brand logo URL. Format `uri`. | | `publicProfile.verified` | boolean | Optional. Whether this assessment verifies the claim. | | `media` | array of object | Required. Ordered media assets. Minimum items `1`. Maximum items `20`. | | `media[].url` | string | Required. Absolute HTTP or HTTPS source link. Format `uri`. | | `media[].type` | string | Required. Declared type for this object. Values: `image`, `video`. | | `media[].position` | integer | Required. Position of this asset in the media sequence. Minimum `1`. Maximum `20`. | | `attachment` | object | Required. Destination attachment for the ad. | | `attachment.type` | string | Required. Declared type for this object. Values: `web_view`, `deep_link`, `app_install`, `lens`, `long_form_video`. | | `attachment.destinationUrl` | string / null | Required. Attachment destination URL. | | `targeting` | object | Required. Ad targeting configuration. | | `targeting.ageMin` | integer / null | Required. Minimum targeted age. | | `targeting.ageMax` | integer / null | Optional. Maximum targeted age. | | `targeting.geos` | array of string | Required. Targeted geographic areas. Minimum items `1`. Maximum items `250`. | | `targeting.languages` | array of string | Optional. Targeted languages. Minimum items `1`. Maximum items `100`. | | `copy` | object | Required. Ad copy and linked title text. | | `copy.body` | string | Optional. Record body. Maximum characters `20000`. | | `copy.caption` | string | Optional. Ad caption. Maximum characters `20000`. | | `copy.linkDescription` | string | Optional. Description of the linked destination. Maximum characters `20000`. | | `copy.sourceTitle` | string | Optional. Title from the submitted source. Maximum characters `20000`. | | `discoverTile` | boolean | Optional. Whether the placement uses a Discover tile. | | `partnershipAd` | boolean | Optional. Whether this is a partnership ad. | | `format` | string / null | Optional. Ad format. | | `arLens` | string / null | Optional. Augmented reality lens information. | | `submittedAt` | string | Optional. Submission timestamp. Format `date-time`. | **Response `202`** | Field | Type | Requirement and meaning | | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------- | | `caseId` | string | Required. Accepted case identifier. Use it for status reads. | | `externalId` | string | Required. Producer identifier. Preserve it across exact retries. | | `status` | string | Required. Current state. Use the declared enum when present. Values: `accepted`, `duplicate`. | | `analysisStatus` | string | Required. Current evaluation state. A decision is available only after completion. Values: `pending`. | | `evaluationId` | string | Required. Evaluation identifier, when available. | | `idempotency` | object | Required. Retry receipt. | | `idempotency.key` | string | Required. Idempotency key. | | `idempotency.replayed` | boolean | Required. Whether this request reuses an earlier submission. | **Response `400`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. | **Response `403`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. | **Response `409`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. | **Response `422`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. | **Response `500`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. |
### `POST /v0/moderation/cases/batch` [#post-v0moderationcasesbatch]
Request and response fields **JSON body** | Field | Type | Requirement and meaning | | ----------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `cases` | array of object | Required. Batch of moderation cases, 1–100 items. Minimum items `1`. Maximum items `100`. | | `cases[].externalId` | string | Required. Producer identifier. Preserve it across exact retries. Minimum characters `1`. Maximum characters `256`. | | `cases[].sourceSystem` | string | Required. Producer system name. Minimum characters `1`. Maximum characters `128`. | | `cases[].sourcePlatform` | string | Required. Source advertising platform. Minimum characters `1`. Maximum characters `128`. | | `cases[].sourceAdId` | string | Required. Source ad identifier. Minimum characters `1`. Maximum characters `256`. | | `cases[].advertiserId` | string | Optional. Identifier of the advertiser. Minimum characters `1`. Maximum characters `256`. | | `cases[].advertiserName` | string | Required. Name of the advertiser. Minimum characters `1`. Maximum characters `500`. | | `cases[].campaignId` | string | Optional. Identifier of the campaign. Minimum characters `1`. Maximum characters `256`. | | `cases[].market` | string | Required. Market for policy evaluation. Minimum characters `1`. Maximum characters `128`. | | `cases[].placement` | string | Required. Ad placement. Minimum characters `1`. Maximum characters `128`. | | `cases[].language` | string | Optional. Language of the submitted content. Default `"en"`. Minimum characters `1`. Maximum characters `64`. | | `cases[].providerMetadata` | object | Optional. Provider metadata retained with the submission. | | `cases[].landingPageUrl` | string / null | Required. Landing page URL. | | `cases[].title` | string | Required. Record title. Minimum characters `1`. Maximum characters `500`. | | `cases[].headline` | string | Optional. Ad headline. Minimum characters `1`. Maximum characters `500`. | | `cases[].brandName` | string | Optional. Advertised brand name. Minimum characters `1`. Maximum characters `500`. | | `cases[].callToAction` | string | Optional. Call-to-action value. Values: `APPLY_NOW`, `BOOK_NOW`, `GET_NOW`, `INSTALL_NOW`, `MORE`, `SHOP_NOW`, `SIGN_UP`, `VIEW`, `WATCH`. | | `cases[].publicProfile` | object | Optional. Public profile information. | | `cases[].publicProfile.displayName` | string | Optional. Customer-visible field label. Minimum characters `1`. Maximum characters `500`. | | `cases[].publicProfile.logoUrl` | string | Optional. Brand logo URL. Format `uri`. | | `cases[].publicProfile.verified` | boolean | Optional. Whether this assessment verifies the claim. | | `cases[].media` | array of object | Required. Ordered media assets. Minimum items `1`. Maximum items `20`. | | `cases[].media[].url` | string | Required. Absolute HTTP or HTTPS source link. Format `uri`. | | `cases[].media[].type` | string | Required. Declared type for this object. Values: `image`, `video`. | | `cases[].media[].position` | integer | Required. Position of this asset in the media sequence. Minimum `1`. Maximum `20`. | | `cases[].attachment` | object | Required. Destination attachment for the ad. | | `cases[].attachment.type` | string | Required. Declared type for this object. Values: `web_view`, `deep_link`, `app_install`, `lens`, `long_form_video`. | | `cases[].attachment.destinationUrl` | string / null | Required. Attachment destination URL. | | `cases[].targeting` | object | Required. Ad targeting configuration. | | `cases[].targeting.ageMin` | integer / null | Required. Minimum targeted age. | | `cases[].targeting.ageMax` | integer / null | Optional. Maximum targeted age. | | `cases[].targeting.geos` | array of string | Required. Targeted geographic areas. Minimum items `1`. Maximum items `250`. | | `cases[].targeting.languages` | array of string | Optional. Targeted languages. Minimum items `1`. Maximum items `100`. | | `cases[].copy` | object | Required. Ad copy and linked title text. | | `cases[].copy.body` | string | Optional. Record body. Maximum characters `20000`. | | `cases[].copy.caption` | string | Optional. Ad caption. Maximum characters `20000`. | | `cases[].copy.linkDescription` | string | Optional. Description of the linked destination. Maximum characters `20000`. | | `cases[].copy.sourceTitle` | string | Optional. Title from the submitted source. Maximum characters `20000`. | | `cases[].discoverTile` | boolean | Optional. Whether the placement uses a Discover tile. | | `cases[].partnershipAd` | boolean | Optional. Whether this is a partnership ad. | | `cases[].format` | string / null | Optional. Ad format. | | `cases[].arLens` | string / null | Optional. Augmented reality lens information. | | `cases[].submittedAt` | string | Optional. Submission timestamp. Format `date-time`. | **Response `202`** | Field | Type | Requirement and meaning | | -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `results` | array of object | Required. Ordered result for every batch input. | | `results[].externalId` | string | Required. Producer identifier. Preserve it across exact retries. | | `results[].caseId` | string | Required. Accepted case identifier. Use it for status reads. | | `results[].status` | string | Required. Current state. Use the declared enum when present. Values: `accepted`, `duplicate`, `rejected`. | | `results[].analysisStatus` | string | Optional. Current evaluation state. A decision is available only after completion. Values: `pending`. | | `results[].evaluationId` | string | Optional. Evaluation identifier, when available. | | `results[].idempotency` | object | Optional. Retry receipt. | | `results[].idempotency.key` | string | Required. Idempotency key. | | `results[].idempotency.replayed` | boolean | Required. Whether this request reuses an earlier submission. | | `results[].errors` | array of string | Optional. Validation messages. | | `results[].message` | string | Optional. Message body. | | `results[].code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `results[].missingFields` | array of string | Optional. Missing input field paths. | | `results[].invalidFields` | array of string | Optional. Invalid input field paths. | **Response `400`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. | **Response `403`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. |
### `GET /v0/moderation/cases/{caseId}` [#get-v0moderationcasescaseid]
Request and response fields **Path and query fields** | Field | Type | Requirement and meaning | | --------------- | ------ | ------------------------------------------------------------------------------------ | | `caseId` (path) | string | Required. Accepted case identifier. Use it for status reads. Minimum characters `1`. | **Response `200`** | Field | Type | Requirement and meaning | | --------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `caseId` | string | Required. Accepted case identifier. Use it for status reads. | | `externalId` | string | Required. Producer identifier. Preserve it across exact retries. | | `analysisStatus` | string | Required. Current evaluation state. A decision is available only after completion. Values: `policy_not_configured`, `pending`, `running`, `completed`, `failed`. | | `evaluationId` | string | Optional. Evaluation identifier, when available. | | `decision` | object | Optional. Completed moderation decision. Read the nested decision fields. | | `decision.disposition` | string | Required. Final disposition of the case. Values: `age_gate`, `approve`, `escalate`, `reject`. | | `decision.confidence` | string | Required. Optional confidence from 0 to 1. Values: `low`, `medium`, `high`. | | `decision.title` | string / null | Required. Record title. Default `null`. | | `decision.reason` | string | Required. Reason for this result. Minimum characters `1`. | | `decision.hits` | array of object | Required. Rules matched by the evaluation. | | `decision.hits[].ruleId` | string | Required. Matched rule identifier. Minimum characters `1`. | | `decision.hits[].ruleSlug` | string | Required. Matched rule slug. Minimum characters `1`. | | `decision.hits[].polarity` | string | Required. Polarity assigned to the assessed claim. Values: `AMBIGUOUS`, `NEGATIVE`, `POSITIVE`. | | `decision.hits[].confidence` | string | Required. Optional confidence from 0 to 1. Values: `low`, `medium`, `high`. | | `decision.hits[].reasoning` | string / null | Required. Explanation of the assessment. | | `decision.hits[].evidence` | array of object | Required. Evidence supporting this assessment. | | `decision.hits[].evidence[].modality` | string | Required. Evidence modality. Values: `image`, `video`, `text`, `metadata`. | | `decision.hits[].evidence[].claim` | string | Required. Claim assessed by the rule. Minimum characters `1`. | | `decision.hits[].evidence[].locator` | object | Optional. Location of evidence within the source. | | `decision.hits[].evidence[].locator.asset` | string | Optional. Media asset assessed by this evidence. Values: `public_profile_logo`. | | `decision.hits[].evidence[].locator.mediaIndex` | integer | Optional. Index of the media asset containing the evidence. Minimum `0`. Maximum `9007199254740991`. | | `decision.hits[].evidence[].locator.boundingBox` | JSON | Optional. Evidence location within an image. | | `decision.hits[].evidence[].locator.startSeconds` | number | Optional. Start of video evidence, in seconds. Minimum `0`. | | `decision.hits[].evidence[].locator.endSeconds` | number | Optional. End of video evidence, in seconds. Minimum `0`. | | `decision.hits[].evidence[].locator.textSpan` | object | Optional. Evidence span within text. | | `decision.hits[].evidence[].locator.textSpan.field` | string | Optional. Field containing the evidence. Minimum characters `1`. Maximum characters `128`. | | `decision.hits[].evidence[].locator.textSpan.start` | integer | Required. Start of the evidence span. Minimum `0`. Maximum `9007199254740991`. | | `decision.hits[].evidence[].locator.textSpan.end` | integer | Required. End of the evidence span. Minimum `0`. Maximum `9007199254740991`. | | `decision.advertiserAssessment` | object | Required. Advertiser assessment in the final decision. | | `decision.advertiserAssessment.polarity` | string | Required. Polarity assigned to the assessed claim. Values: `AMBIGUOUS`, `NEGATIVE`, `POSITIVE`. | | `decision.advertiserAssessment.reasoning` | string | Required. Explanation of the assessment. Minimum characters `1`. Maximum characters `1000`. | | `decision.landingAssessment` | object | Required. Landing page assessment in the final decision. | | `decision.landingAssessment.polarity` | string | Required. Polarity assigned to the assessed claim. Values: `AMBIGUOUS`, `NEGATIVE`, `POSITIVE`. | | `decision.landingAssessment.reasoning` | string | Required. Explanation of the assessment. Minimum characters `1`. Maximum characters `1000`. | | `decision.decisionSource` | string | Required. Origin of the decision. Default `"model"`. Values: `model`, `fail_closed`. | | `decision.failureCode` | string / null | Required. Machine-readable evaluation failure. Default `null`. | | `decision.failureMessage` | string / null | Required. Human-readable failure message. Default `null`. | | `failureCode` | string | Optional. Machine-readable evaluation failure. | **Response `403`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. | **Response `404`** | Field | Type | Requirement and meaning | | --------------- | --------------- | --------------------------------------------------------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | | `message` | string | Optional. Message body. | | `code` | string | Optional. Machine-readable error code. Values: `MODERATION_INPUT_INCOMPLETE`, `MODERATION_INPUT_INVALID`. | | `missingFields` | array of string | Optional. Missing input field paths. | | `invalidFields` | array of string | Optional. Invalid input field paths. | | `supported` | array of string | Optional. Whether evidence supports this claim. |
### `POST /v0/ingest/records` [#post-v0ingestrecords]
Request and response fields **JSON body** | Field | Type | Requirement and meaning | | ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `platform` | string | Required. Source platform. Values: `DISCORD`, `SLACK`, `GITHUB`, `ZENDESK`, `TELEGRAM`, `FACEBOOK_GROUP`, `TWITTER_COMMUNITY`, `SALESFORCE`, `FACEBOOK`, `TWITTER`, `THREADS`, `TIKTOK`, `INSTAGRAM`, `LINKEDIN`, `WHATSAPP`, `YOUTUBE`, `GAINSIGHT`, `APPSTORE`, `GOOGLE_PLAY`, `HIGHER_LOGIC`, `DISCOURSE`, `CUSTOM_FORM`, `MODERATION_API`, `CHROME_WEB_STORE`, `CANNY`. | | `serverId` | string | Required. Source account or community identifier. Minimum characters `1`. | | `serverName` | string | Required. Source account or community name. Minimum characters `1`. | | `channelId` | string | Optional. Source channel identifier. | | `channelName` | string | Optional. Source channel name. | | `processingLevel` | string | Optional. INSIGHTS for normal insight processing, or STATS\_ONLY for statistics-only processing. Values: `INSIGHTS`, `STATS_ONLY`. | | `source` | object | Optional. Producer origin metadata. | | `source.system` | string | Required. Producer system name. Minimum characters `1`. | | `source.sourceId` | string | Optional. Producer source identifier. | | `records` | array of object | Required. Normalized record batch, 1–500 items. Minimum items `1`. Maximum items `500`. | | `records[].externalId` | string | Required. Producer identifier. Preserve it across exact retries. Minimum characters `1`. | | `records[].threadExternalId` | string | Optional. Producer thread identifier. | | `records[].parentExternalId` | string | Optional. Producer parent identifier. | | `records[].authorId` | string | Required. Author identifier. Minimum characters `1`. | | `records[].authorName` | string | Required. Producer author name. Minimum characters `1`. | | `records[].title` | string | Optional. Record title. | | `records[].body` | string | Required. Record body. | | `records[].score` | number | Optional. Optional score from 0 to 5. Minimum `0`. Maximum `5`. | | `records[].createdAt` | string | Required. Creation timestamp. Minimum characters `1`. | | `records[].url` | string | Optional. Absolute HTTP or HTTPS source link. | | `records[].recordType` | string | Required. Source record type. Minimum characters `1`. | | `records[].customFields` | object | Optional. Organization-defined field names and values. | **Response `202`** | Field | Type | Requirement and meaning | | ---------- | ------ | -------------------------------------------------------------------------------- | | `status` | string | Required. Current state. Use the declared enum when present. Values: `accepted`. | | `accepted` | number | Required. Number of accepted input records. | **Response `403`** | Field | Type | Requirement and meaning | | --------- | ------- | -------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | **Response `422`** | Field | Type | Requirement and meaning | | --------- | ------- | -------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. | **Response `500`** | Field | Type | Requirement and meaning | | --------- | ------- | -------------------------------------------------------- | | `success` | boolean | Required. Whether the request succeeds. Values: `False`. | | `error` | string | Required. Error message. |
## Write behavior [#write-behavior] Custom field writes require a write-scoped key. Values must match the organization's registered field types. A validation failure can return `fieldErrors`. Read the field definitions before writing a value. Moderation intake requires the organization's `ad_policy` mode and a write-scoped key. An unchanged `externalId` with unchanged content returns `duplicate` on an exact retry. Conflicting content for an existing ID returns `409` for a single case. Batch results remain ordered and report per-item rejection. Poll the returned `caseId`. A decision appears only after the current evaluation completes. Normalized ingestion accepts 1–500 records and returns asynchronous acceptance. Acceptance does not prove processing is complete. Record identity uses the organization, platform, server, and external ID. Preserve these identifiers for retries. ## Tips [#tips] * Keep identifiers as strings and preserve nullable values. * Validate response fields before reusing them in another request. * Read [Metrics reference](/docs/developer/metrics-reference) before interpreting metric units. * Do not mix REST response envelopes with MCP operation envelopes. ## Related [#related] First request, endpoint selection, and error handling. Agent tool contracts and operation discovery. Choose the right filter field and grammar.