Developer
API field reference
Every REST endpoint below lists its query, path, body, and response fields. Read this with the API guide.
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 |
What you're 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
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
GET /v0/action/list
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}
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
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
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
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}
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
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
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
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
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
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
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
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
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
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}
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
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
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
- Keep identifiers as strings and preserve nullable values.
- Validate response fields before reusing them in another request.
- Read Metrics reference before interpreting metric units.
- Do not mix REST response envelopes with MCP operation envelopes.