{"openapi":"3.0.0","info":{"title":"Sift API","description":"REST API for Sift data with API key authentication.\n\n## Authentication and scopes\nSend the key in the `x-api-key` header. The gateway checks the key on every request.\n- A GET or HEAD needs the `read` scope. A POST, PUT, PATCH or DELETE needs the `write` scope.\n- `/v0/sources/*` (Custom API) needs `ingest:read` for a GET and `ingest` for other methods. A key with source ids reads only those sources.\n- `/v0/audit-events` needs `audit:read`. Only a Super Admin can create a key with that scope (the **Audit log** profile).\n- A key without the scope gets 403 `{\"success\": false, \"error\": \"Missing required scope: <scope>\"}`.\n- A revoked or expired key gets 401 `{\"success\": false, \"error\": \"Invalid or expired API key\"}` on its next request.\n- A new key expires after 90 days by default. A key made before 2026-10-08 does not expire.\n\n## Changes since 2026-08-20\nEach item names the routes it changes. **Breaking** marks a change that can give an existing client a different answer.\n\n**Scores (2026-10-20)**\n- **Breaking.** `sentiment` on `/action/:id`, `/action/list` and `/conversations/search` was Positive (5-10), Neutral (4) or Negative (0-3). It is now a level: Very Negative (1-2), Negative (3-4), Neutral (5-6), Positive (7-8) or Very Positive (9-10). It is null when the case is not analyzed (score 0). `sentimentScore` is unchanged.\n- **Breaking.** `/analytics/sentiment` and `/analytics/sentiment/by-tag` count by the same levels: Very Negative 1-2, Negative 3-4, Neutral 5-6, Positive 7-10. Before, they counted 0-1, 2, 3-5 and 6-10. A case with score 0 is in no count.\n- **Breaking.** In `filterJson`, a number on a score must cover whole levels. `sentiment<=4` works. `sentiment<4` splits a level and returns 400. `fullFilter` and the search `filter` keep any number, and also take level names (`sentiment=Negative,\"Very Negative\"`).\n\n**Case list and search filters (2026-10-17)**\n- **Breaking.** `/action/list`: every clause of `filter` and `filterJson` now applies. Before, only `ro` applied, and `src`, `st`, `q` and the other clauses were ignored.\n- **Breaking.** `/action/list` returns 400 for an unknown name, for `filter` and `filterJson` sent together, for text that does not parse, and for a filter over 10,000 characters. Before, these were dropped without an error.\n- **Breaking.** `/action/list` and `/conversations/search` return 400 for a tag, channel or queue value that is not an id in your organization. Before, the value matched nothing or was ignored.\n- **Breaking.** `/conversations/search` adds a 30-day `createdAt` window when the filter does not bound `createdAt`. Before, the window applied only when there was no filter.\n- `/action/list` with only `to` reads the 7 days before `to`. Before, it read from 7 days ago until `to`.\n- **Breaking.** `includeFullConversation=false` (`/action/list`) and `respondedOnly=false` (`/analytics/tags`, `/analytics/tags/volume`) now mean false. Before, any value meant true. These booleans take only true/false, 1/0, yes/no, on/off, y/n or enabled/disabled.\n- `/action/list` takes `fullFilter`, the full filter text of the Search page. `pageSize` must be a whole number.\n\n**Responses**\n- **Breaking.** `/conversations/search` rows have the same fields as `/action/list` rows, plus `threadId`, `easyId` and `contributors`.\n- `/action/:id` adds `user.followerCount`. `/action/list` and search rows add `userFollowerCount`.\n- **Breaking.** `/agents` and `/agents/:id` do not count placeholder agent ids (N/A, None, Unknown, undefined) as agents. An action assigned to `sift_ai` is no longer counted for `sift_ai` unless `sift_ai` is its primary agent.\n- `/actions/:actionId/custom-fields` also takes the source thread id.\n\n**Authentication (2026-10-08)**\n- **Breaking.** The gateway checks the key and its scope on every request (see above). Before, a GET needed no scope, and a revoked key worked for up to 5 minutes.\n\n**Ingest and Custom API**\n- **Breaking.** `/ingest/records`: `records[].url` must be an absolute http or https URL. Other URLs return 400.\n- `/ingest/records` returns 422 for platform `CUSTOM_API`. Use the Custom API routes for that source.\n- New Custom API routes under `/v0/sources/{sourceId}/`: import one item or up to 100, validate an item, read receipts, retry failed work, and correct an imported item.\n","version":"1.0.0"},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{}},"paths":{"/v0/sources/{sourceId}/items":{"post":{"summary":"Import one item","tags":["Custom API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":256},"channelExternalId":{"default":"default","type":"string","minLength":1,"maxLength":256},"threadExternalId":{"type":"string","minLength":1,"maxLength":256},"parentExternalId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","maxLength":2000},"text":{"type":"string","minLength":1,"maxLength":64000},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"sourceUrl":{"type":"string","format":"uri"},"author":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":256},"name":{"type":"string","minLength":1,"maxLength":256},"username":{"type":"string","maxLength":256},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"avatarUrl":{"type":"string","format":"uri"},"profileUrl":{"type":"string","format":"uri"},"customFields":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}}},"required":["externalId","name"],"additionalProperties":false},"customFields":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"tagIds":{"default":[],"maxItems":32,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"An 8-4-4-4-12 hex identifier. Accepts any uuid-shaped value, not only RFC 4122-compliant ones: some existing rows predate an RFC-compliant id generator, and Postgres's uuid column accepts them, so the schema must too."}}},"required":["externalId","text","occurredAt","author"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/sources/{sourceId}/items/batch":{"post":{"summary":"Import up to 100 items","tags":["Custom API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":256},"channelExternalId":{"default":"default","type":"string","minLength":1,"maxLength":256},"threadExternalId":{"type":"string","minLength":1,"maxLength":256},"parentExternalId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","maxLength":2000},"text":{"type":"string","minLength":1,"maxLength":64000},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"sourceUrl":{"type":"string","format":"uri"},"author":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":256},"name":{"type":"string","minLength":1,"maxLength":256},"username":{"type":"string","maxLength":256},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"avatarUrl":{"type":"string","format":"uri"},"profileUrl":{"type":"string","format":"uri"},"customFields":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}}},"required":["externalId","name"],"additionalProperties":false},"customFields":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"tagIds":{"default":[],"maxItems":32,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"An 8-4-4-4-12 hex identifier. Accepts any uuid-shaped value, not only RFC 4122-compliant ones: some existing rows predate an RFC-compliant id generator, and Postgres's uuid column accepts them, so the schema must too."}}},"required":["externalId","text","occurredAt","author"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/sources/{sourceId}/items/validate":{"post":{"summary":"Validate without storing","tags":["Custom API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":256},"channelExternalId":{"default":"default","type":"string","minLength":1,"maxLength":256},"threadExternalId":{"type":"string","minLength":1,"maxLength":256},"parentExternalId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","maxLength":2000},"text":{"type":"string","minLength":1,"maxLength":64000},"occurredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"sourceUrl":{"type":"string","format":"uri"},"author":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":256},"name":{"type":"string","minLength":1,"maxLength":256},"username":{"type":"string","maxLength":256},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"avatarUrl":{"type":"string","format":"uri"},"profileUrl":{"type":"string","format":"uri"},"customFields":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}}},"required":["externalId","name"],"additionalProperties":false},"customFields":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"default":{},"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"tagIds":{"default":[],"maxItems":32,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$","description":"An 8-4-4-4-12 hex identifier. Accepts any uuid-shaped value, not only RFC 4122-compliant ones: some existing rows predate an RFC-compliant id generator, and Postgres's uuid column accepts them, so the schema must too."}}},"required":["externalId","text","occurredAt","author"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/sources/{sourceId}/receipts":{"get":{"summary":"Read recent receipts","tags":["Custom API"],"parameters":[{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/sources/{sourceId}/receipts/{receiptId}":{"get":{"summary":"Read one receipt","tags":["Custom API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"receiptId","required":true,"description":"An 8-4-4-4-12 hex identifier. Accepts any uuid-shaped value, not only RFC 4122-compliant ones: some existing rows predate an RFC-compliant id generator, and Postgres's uuid column accepts them, so the schema must too."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/sources/{sourceId}/receipts/{receiptId}/retry":{"post":{"summary":"Retry failed work","tags":["Custom API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"in":"path","name":"receiptId","required":true,"description":"An 8-4-4-4-12 hex identifier. Accepts any uuid-shaped value, not only RFC 4122-compliant ones: some existing rows predate an RFC-compliant id generator, and Postgres's uuid column accepts them, so the schema must too."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/sources/{sourceId}/items/{externalId}":{"patch":{"summary":"Correct imported content","tags":["Custom API"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expectedRevision":{"type":"integer","minimum":1,"maximum":9007199254740991},"requestId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"text":{"type":"string","minLength":1,"maxLength":64000},"title":{"type":"string","maxLength":2000},"customFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}},"metadata":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema1"}}},"required":["expectedRevision","requestId"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":30},"in":"path","name":"sourceId","required":true},{"schema":{"type":"string","minLength":1,"maxLength":256},"in":"path","name":"externalId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response"}}}},"/v0/action/list":{"get":{"summary":"Get actions list","tags":["v0"],"description":"Retrieve a list of actions with optional filtering.\n\n**Default Behavior:**\n- Returns actions from the past 7 days, unless the filter holds a createdAt range. With only `to`, it returns the 7 days before `to`\n- Only includes actions with at least one agent response (ro=true)\n- Results are sorted by `createdAt` descending (newest first)\n\n**Sorting & Date Filtering:**\nThe `sortBy` parameter controls which date field is used for both the `from`/`to` date range filter and the sort order:\n- `sortBy=createdAt` (default) - Filter and sort by action creation time\n- `sortBy=updatedAt` - Filter and sort by the case's last change (status, queue, assignee, new message)\n\nThe `from` and `to` parameters accept ISO 8601 date strings. You can pass a date (`2024-01-01`) or a full datetime (`2024-01-01T14:30:00Z`). Date-only values are interpreted as midnight UTC. `to` is exclusive (`<`): `to=2024-01-31` means up to midnight at the start of Jan 31. Use `to=2024-02-01` to include the full day.\n\nTo page through results, adjust the `from`/`to` window based on the relevant timestamp from the last record returned. A window whose `to` precedes its `from` holds no actions and returns an empty page.\n\n**Filter DSL Syntax:**\nThe `filter` parameter accepts a simple DSL for filtering:\n- `ro=true` - Only responded actions (default)\n- `ro=false` - Include all actions\n- `src=TWITTER` - Filter by source platform\n- `st=OPEN` - Filter by status\n- `q=<uuid>` - Filter by queue ID\n- Multiple filters: `ro=true+src=TWITTER` (AND logic)\n\n**Full filter (`fullFilter`):**\nThe `filter` and `filterJson` parameters read the short names listed above and answer 400 for a name they do not know. To use the full set of fields, send `fullFilter` with the Operations DSL (the same text as the Search page filter bar). It adds no responded default. Do not send it with `filter` or `filterJson`. A text that does not parse returns 400.\n\n**Errors:** every clause of `filter` and `filterJson` applies. The route returns 400 for an unknown name, for `filter` and `filterJson` sent together, for text that does not parse, for a filter over 10,000 characters, and for a tag, channel or queue value that is not an id in your organization.\n\n**Scores in filters:** `sentiment`, `relevance`, `actionability` and `csat` take a number (`sentiment<=4`, `sentiment=1..4`) or level names (`sentiment=Negative,\"Very Negative\"`). The sentiment, relevance and actionability levels split the 1-10 score in five: 1-2, 3-4, 5-6, 7-8 and 9-10. In `filterJson`, a number on a score must cover whole levels: `sentiment<=4` works, but `sentiment<4` splits a level and returns 400.\n\n**Examples:**\n```\n?fullFilter=src=TWITTER+kw~refund       # Full filter (Operations DSL)\n?filter=ro=true                    # Responded actions only (default)\n?filter=ro=false                   # All actions including unresponded\n?filter=ro=true+src=TWITTER        # Responded Twitter actions\n?from=2024-01-01&to=2024-01-31     # Custom date range\n?sortBy=updatedAt&from=2024-01-01  # Recently updated actions\n```","parameters":[{"schema":{},"in":"query","name":"from","required":false,"description":"Start date (ISO 8601). Accepts date (2024-01-01) or datetime (2024-01-01T14:30:00Z). Date-only values are midnight UTC."},{"schema":{},"in":"query","name":"to","required":false,"description":"End date (ISO 8601, inclusive <=). Use next day or T23:59:59Z to include the full end date."},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":500},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string"},"in":"query","name":"filter","required":false},{"schema":{"type":"string"},"in":"query","name":"filterJson","required":false},{"schema":{"type":"string","maxLength":10000},"in":"query","name":"fullFilter","required":false,"description":"Full filter in the Operations DSL (the text of the Search page filter bar), for example `src=TWITTER+kw~refund`. Every leaf applies. No responded default is added. Do not send it with `filter` or `filterJson`. The route description lists how scores filter."},{"schema":{"type":"string"},"in":"query","name":"includeFullConversation","required":false,"description":"A boolean takes `true` or `false`."},{"schema":{"default":"createdAt","type":"string","enum":["createdAt","updatedAt"]},"in":"query","name":"sortBy","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"actionId":{"type":"string"},"actionTitle":{"type":"string"},"actionSummary":{"type":"string"},"status":{"type":"string"},"platform":{"type":"string"},"recordType":{"nullable":true,"type":"string"},"isPublicPost":{"type":"boolean"},"siftURL":{"type":"string"},"sourceURL":{"nullable":true,"type":"string"},"queue":{"nullable":true,"type":"string"},"initialQueue":{"nullable":true,"type":"string"},"sentiment":{"nullable":true,"description":"The sentiment level: Very Negative, Negative, Neutral, Positive or Very Positive. Null when the case is not analyzed.","type":"string"},"sentimentScore":{"nullable":true,"description":"The sentiment score, 1 to 10. 0 is not analyzed.","type":"number"},"moderation":{"nullable":true,"type":"string"},"assigneeName":{"nullable":true,"type":"string"},"assigneeEmail":{"nullable":true,"type":"string"},"assigneeUserId":{"nullable":true,"type":"string"},"assigneeRole":{"nullable":true,"type":"string"},"userName":{"type":"string"},"userUsername":{"type":"string"},"userId":{"type":"string"},"userEmail":{"nullable":true,"type":"string"},"userFollowerCount":{"nullable":true,"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"nullable":true,"type":"string"},"initialMessageTime":{"nullable":true,"type":"string"},"initialResponseTime":{"nullable":true,"type":"string"},"closeTime":{"nullable":true,"type":"string"},"claimTime":{"nullable":true,"type":"string"},"firstResponseTime":{"nullable":true,"type":"string"},"handleTime":{"nullable":true,"type":"string"},"serverName":{"type":"string"},"channelName":{"type":"string"},"csatScore":{"nullable":true,"type":"string"},"csatFeedback":{"nullable":true,"type":"string"},"estimatedCSAT":{"nullable":true,"type":"number"},"totalMessages":{"nullable":true,"type":"number"},"totalUserMessages":{"nullable":true,"type":"number"},"totalAgentMessages":{"nullable":true,"type":"number"},"tags":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"group":{"type":"string"}},"required":["value","group"],"additionalProperties":false}},"closingTags":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"group":{"type":"string"}},"required":["value","group"],"additionalProperties":false}},"customFields":{"type":"object","additionalProperties":{}},"rootMessageText":{"nullable":true,"type":"string"},"conversationJson":{"nullable":true,"type":"string"}},"required":["actionId","actionTitle","actionSummary","status","platform","recordType","isPublicPost","siftURL","sourceURL","queue","initialQueue","sentiment","sentimentScore","moderation","assigneeName","assigneeEmail","assigneeUserId","assigneeRole","userName","userUsername","userId","userEmail","userFollowerCount","createdAt","updatedAt","initialMessageTime","initialResponseTime","closeTime","claimTime","firstResponseTime","handleTime","serverName","channelName","csatScore","csatFeedback","estimatedCSAT","totalMessages","totalUserMessages","totalAgentMessages","tags","closingTags","customFields","rootMessageText","conversationJson"],"additionalProperties":false}},"totalRecords":{"type":"number"},"currentPage":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["data","totalRecords","currentPage","pageSize","totalPages"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/action/{id}":{"get":{"summary":"Get action by ID","tags":["v0"],"description":"Retrieve detailed information about a specific action","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"name":{"type":"string"},"username":{"type":"string"},"userId":{"type":"string"},"email":{"nullable":true,"type":"string"},"followerCount":{"nullable":true,"type":"number"}},"required":["name","username","userId","email","followerCount"],"additionalProperties":false},"actionId":{"type":"string"},"actionTitle":{"type":"string"},"actionSummary":{"type":"string"},"platform":{"type":"string"},"recordType":{"nullable":true,"type":"string"},"isPublicPost":{"type":"boolean"},"sentiment":{"nullable":true,"description":"The sentiment level: Very Negative, Negative, Neutral, Positive or Very Positive. Null when the case is not analyzed.","type":"string"},"sentimentScore":{"nullable":true,"description":"The sentiment score, 1 to 10. 0 is not analyzed.","type":"number"},"queue":{"nullable":true,"type":"string"},"initialQueue":{"nullable":true,"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"siftURL":{"type":"string"},"sourceURL":{"nullable":true,"type":"string"},"updatedAt":{"nullable":true,"type":"string"},"initialMessageTime":{"nullable":true,"type":"string"},"initialResponseTime":{"nullable":true,"type":"string"},"closeTime":{"nullable":true,"type":"string"},"firstResponseTime":{"nullable":true,"type":"string"},"handleTime":{"nullable":true,"type":"string"},"claimTime":{"nullable":true,"type":"string"},"assignee":{"type":"object","properties":{"name":{"nullable":true,"type":"string"},"email":{"nullable":true,"type":"string"},"userId":{"nullable":true,"type":"string"},"role":{"nullable":true,"type":"string"}},"required":["name","email","userId","role"],"additionalProperties":false},"serverName":{"type":"string"},"channelName":{"type":"string"},"tags":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"group":{"type":"string"}},"required":["value","group"],"additionalProperties":false}},"closingTags":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"group":{"type":"string"}},"required":["value","group"],"additionalProperties":false}},"moderation":{"nullable":true,"type":"string"},"comments":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"authorNativeId":{"type":"string"},"authorNativeName":{"nullable":true,"type":"string"}},"required":["text","authorNativeId","authorNativeName"],"additionalProperties":false}},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string"},"author":{"type":"string"},"authorId":{"type":"string"},"authorType":{"type":"string","enum":["USER","AGENT","BOT"]},"message":{"type":"string"},"mediaUrls":{"type":"array","items":{"type":"string"}}},"required":["id","timestamp","author","authorType","message","mediaUrls"],"additionalProperties":false}},"rootMessageText":{"nullable":true,"type":"string"},"conversation":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"timestamp":{"type":"string"},"author":{"type":"string"},"authorId":{"nullable":true,"type":"string"},"authorType":{"type":"string","enum":["USER","AGENT","BOT"]},"message":{"type":"string"},"parentMessageId":{"nullable":true,"type":"string"},"mediaUrls":{"type":"array","items":{"type":"string"}}},"required":["id","timestamp","author","authorId","authorType","message","parentMessageId","mediaUrls"],"additionalProperties":false}},"customFields":{"type":"object","additionalProperties":{}},"csatScore":{"nullable":true,"type":"string"},"csatFeedback":{"nullable":true,"type":"string"},"estimatedCSAT":{"nullable":true,"type":"number"},"totalMessages":{"nullable":true,"type":"number"},"totalUserMessages":{"nullable":true,"type":"number"},"totalAgentMessages":{"nullable":true,"type":"number"}},"required":["user","actionId","actionTitle","actionSummary","platform","recordType","isPublicPost","sentiment","sentimentScore","queue","initialQueue","status","createdAt","siftURL","sourceURL","updatedAt","initialMessageTime","initialResponseTime","closeTime","firstResponseTime","handleTime","claimTime","assignee","serverName","channelName","tags","closingTags","moderation","comments","messages","rootMessageText","customFields","csatScore","csatFeedback","estimatedCSAT","totalMessages","totalUserMessages","totalAgentMessages"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/actions/{actionId}/custom-fields":{"patch":{"summary":"Set custom fields on an action","tags":["v0"],"description":"Set one or more case-level (ActionableInsightsThread) custom fields on an action. `actionId` takes the easy id (`AAS-100`), the action id or the source thread id. Requires the `write` scope. Each `fieldName` is validated against the org's OrgCustomField definitions; unknown fields are rejected with per-field errors. Optional `confidence` (0–1) and `rationale` are recorded on the value's provenance sidecar.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"fieldName":{"type":"string","minLength":1},"value":{},"confidence":{"type":"number","minimum":0,"maximum":1},"rationale":{"type":"string"}},"required":["fieldName"]}}},"required":["fields"]}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"actionId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"actionId":{"type":"string"},"updated":{"type":"array","items":{"type":"object","properties":{"fieldName":{"type":"string"},"value":{}},"required":["fieldName","value"],"additionalProperties":false}}},"required":["actionId","updated"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}}}},"get":{"summary":"Get an action's custom fields","tags":["v0"],"description":"Return the current case-level custom field values on an action, with their display metadata and provenance. `actionId` takes the easy id (`AAS-100`), the action id or the source thread id. Requires the `read` scope.","parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"actionId","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"actionId":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"fieldName":{"type":"string"},"displayName":{"type":"string"},"fieldType":{"type":"string"},"value":{},"provenance":{}},"required":["fieldName","displayName","fieldType","value"],"additionalProperties":false}}},"required":["actionId","fields"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"fieldErrors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/agents":{"get":{"summary":"Get agents list with metrics","tags":["v0"],"description":"Retrieve a list of all agents with their performance metrics and workload.\n\nAn action counts for its primary agent, else its assignee. Placeholder ids (N/A, None, Unknown, undefined) are no agent, and the system assignee `sift_ai` counts only as a primary agent.\n\n**Metrics include:**\n- Total actions handled\n- Response time (median)\n- Handle time (median)\n- CSAT scores (actual and estimated)\n- Resolution quality, sentiment change\n- Current workload (active, closed, cancelled)\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 30 days ago)\n- `to` - End date (ISO string, default: now)","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"agentId":{"type":"string"},"metrics":{"type":"object","properties":{"totalActions":{"type":"number"},"totalActionsWithResponse":{"type":"number"},"totalMessages":{"type":"number"},"totalAgentMessages":{"type":"number"},"totalUserMessages":{"type":"number"},"averageCsat":{"type":"number"},"averageResponseTime":{"type":"number"},"averageHandleTime":{"type":"number"},"averageEstimatedCsat":{"type":"number"},"averageResolutionQuality":{"type":"number"},"averageSentimentChange":{"type":"number"},"averageRubricScore":{"type":"number"}},"required":["totalActions","totalActionsWithResponse","totalMessages","totalAgentMessages","totalUserMessages","averageCsat","averageResponseTime","averageHandleTime","averageEstimatedCsat","averageResolutionQuality","averageSentimentChange","averageRubricScore"],"additionalProperties":false},"workload":{"type":"object","properties":{"active":{"type":"number"},"closed":{"type":"number"},"cancelled":{"type":"number"}},"required":["active","closed","cancelled"],"additionalProperties":false}},"required":["agentId","metrics","workload"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/agents/{id}":{"get":{"summary":"Get agent details","tags":["v0"],"description":"Retrieve detailed metrics and performance data for a specific agent.\n\n**Returns:**\n- Individual action/ticket metrics\n- Aggregated performance metrics\n- Current workload breakdown\n- Queue assignments","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false},{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"metrics":{"type":"array","items":{"type":"object","additionalProperties":{}}},"aggregatedMetrics":{"type":"object","properties":{"totalActions":{"type":"number"},"totalMessages":{"type":"number"},"totalAgentMessages":{"type":"number"},"totalUserMessages":{"type":"number"},"averageCsat":{"type":"number"},"averageResponseTime":{"type":"number"},"averageHandleTime":{"type":"number"},"averageEstimatedCsat":{"type":"number"},"averageResolutionQuality":{"type":"number"},"averageSentimentChange":{"type":"number"},"averageRubricScore":{"type":"number"}},"required":["totalActions","totalMessages","totalAgentMessages","totalUserMessages","averageCsat","averageResponseTime","averageHandleTime","averageEstimatedCsat","averageResolutionQuality","averageSentimentChange","averageRubricScore"],"additionalProperties":false},"currentWorkload":{"type":"object","properties":{"active":{"type":"number"},"closed":{"type":"number"},"cancelled":{"type":"number"}},"required":["active","closed","cancelled"],"additionalProperties":false},"queues":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["metrics","aggregatedMetrics","currentWorkload","queues"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/audit-events":{"get":{"summary":"List audit log events","tags":["v0"],"description":"One page of the organization's audit log, newest first. Use it to feed a SIEM.\n\nThe key needs the `audit:read` scope: create it in Settings → API keys with the **Audit log** profile. Only a Super Admin can create that key.\n\n**Polling:** read pages with `cursor` until `nextCursor` is null. On the next poll, set `from` to the `createdAt` of the newest event you stored, and drop any event `id` you already have.\n\n**Query Parameters:**\n- `from`, `to` - Time window (ISO 8601). Omit for no bound.\n- `types` - Comma-separated event types, for example `USER_SIGNED_IN,EXPORT_DOWNLOADED`.\n- `actorId` - One actor's events.\n- `cursor` - The `nextCursor` from the previous page.","parameters":[{"schema":{},"in":"query","name":"from","required":false,"description":"Keep events at or after this time (ISO 8601). Omit for no lower bound."},{"schema":{},"in":"query","name":"to","required":false,"description":"Keep events at or before this time (ISO 8601). Omit for no upper bound."},{"schema":{"type":"string"},"in":"query","name":"types","required":false,"description":"Comma-separated event types to keep, for example `USER_SIGNED_IN,API_KEY_CREATED`."},{"schema":{"type":"string"},"in":"query","name":"actorId","required":false,"description":"Keep only one actor's events."},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"The `nextCursor` from the previous page."}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"actorId":{"nullable":true,"type":"string"},"actorName":{"nullable":true,"type":"string"},"targetId":{"nullable":true,"type":"string"},"targetName":{"nullable":true,"type":"string"},"metadata":{},"createdAt":{"type":"string","format":"date-time"},"viaAgent":{"nullable":true,"type":"string"}},"required":["id","type","actorId","actorName","targetId","targetName","metadata","createdAt","viaAgent"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"}},"required":["success","data","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/queues":{"get":{"summary":"Get queues list with metrics","tags":["v0"],"description":"Retrieve a list of all queues with their performance metrics and workload.\n\n**Metrics include:**\n- Total actions handled\n- Response time (median)\n- Handle time (median)\n- CSAT scores (actual and estimated)\n- Resolution quality, sentiment metrics\n- Current workload (active, closed, cancelled)\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 30 days ago)\n- `to` - End date (ISO string, default: now)","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"queueId":{"nullable":true,"type":"string"},"queueName":{"nullable":true,"type":"string"},"metrics":{"type":"object","properties":{"totalActions":{"type":"number"},"totalMessages":{"type":"number"},"totalAgentMessages":{"type":"number"},"totalUserMessages":{"type":"number"},"averageCsat":{"type":"number"},"averageResponseTime":{"type":"number"},"averageHandleTime":{"type":"number"},"averageEstimatedCsat":{"type":"number"},"averageResolutionQuality":{"type":"number"},"averageSentimentChange":{"type":"number"},"averageRubricScore":{"type":"number"},"averageSentimentScore":{"type":"number"}},"required":["totalActions","totalMessages","totalAgentMessages","totalUserMessages","averageCsat","averageResponseTime","averageHandleTime","averageEstimatedCsat","averageResolutionQuality","averageSentimentChange","averageRubricScore","averageSentimentScore"],"additionalProperties":false},"workload":{"type":"object","properties":{"active":{"type":"number"},"closed":{"type":"number"},"cancelled":{"type":"number"}},"required":["active","closed","cancelled"],"additionalProperties":false}},"required":["queueId","queueName","metrics","workload"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/analytics/tags":{"get":{"summary":"Get tag analytics dashboard","tags":["v0"],"description":"Retrieve comprehensive tag statistics including:\n- Summary metrics (total tags, tag groups, tagged records, actions)\n- Tag breakdown with distribution percentages\n- Volume by tag with response status and sentiment metrics\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 7 days ago)\n- `to` - End date (ISO string, default: now)\n- `respondedOnly` - Only include responded actions (default: false). Takes true/false, 1/0, yes/no or on/off\n- `limit` - Number of tags to return (default: 10)\n- `offset` - Pagination offset (default: 0)\n- `search` - Filter tags by name","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false},{"schema":{"type":"string"},"in":"query","name":"respondedOnly","required":false,"description":"A boolean takes `true` or `false`."},{"schema":{"type":"number"},"in":"query","name":"limit","required":false},{"schema":{"type":"number"},"in":"query","name":"offset","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"summary":{"type":"object","properties":{"totalTags":{"type":"number"},"totalTagGroups":{"type":"number"},"totalTaggedRecords":{"type":"number"},"totalActions":{"type":"number"}},"required":["totalTags","totalTagGroups","totalTaggedRecords","totalActions"],"additionalProperties":false},"tagBreakdown":{"type":"array","items":{"type":"object","properties":{"tagId":{"type":"string"},"tagName":{"type":"string"},"groupName":{"nullable":true,"type":"string"},"count":{"type":"number"},"percentage":{"type":"number"}},"required":["tagId","tagName","groupName","count","percentage"],"additionalProperties":false}},"volumeByTag":{"type":"array","items":{"type":"object","properties":{"tagId":{"type":"string"},"tagName":{"type":"string"},"total":{"type":"number"},"responded":{"type":"number"},"notResponded":{"type":"number"},"avgSentiment":{"nullable":true,"type":"number"},"avgActionability":{"nullable":true,"type":"number"},"avgRelevance":{"nullable":true,"type":"number"}},"required":["tagId","tagName","total","responded","notResponded","avgSentiment","avgActionability","avgRelevance"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"],"additionalProperties":false}},"required":["summary","tagBreakdown","volumeByTag","pagination"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/analytics/tags/volume":{"get":{"summary":"Get tag volume over time","tags":["v0"],"description":"Retrieve daily volume data for top tags, formatted for chart visualization.\n\n**Returns:**\n- `data` - Array of daily counts: `{ date: \"2024-01-01\", \"Billing\": 10, \"Support\": 5 }`\n- `tags` - List of tag names included in the data\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 7 days ago)\n- `to` - End date (ISO string, default: now)\n- `respondedOnly` - Only include responded actions (default: false). Takes true/false, 1/0, yes/no or on/off\n- `topTagsLimit` - Number of top tags to include (default: 5)\n- `tagIds` - Comma-separated specific tag IDs to include","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false},{"schema":{"type":"string"},"in":"query","name":"respondedOnly","required":false,"description":"A boolean takes `true` or `false`."},{"schema":{"type":"number"},"in":"query","name":"topTagsLimit","required":false},{"schema":{"type":"string"},"in":"query","name":"tagIds","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"}]}}},"tags":{"type":"array","items":{"type":"string"}}},"required":["data","tags"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/analytics/sentiment":{"get":{"summary":"Get daily sentiment distribution","tags":["v0"],"description":"Retrieve sentiment breakdown by day.\n\n**Returns array of:**\n- `day` - Date string\n- `Very Negative` - Count (sentiment 1 to 2)\n- `Negative` - Count (sentiment 3 to 4)\n- `Neutral` - Count (sentiment 5 to 6)\n- `Positive` - Count (sentiment 7 to 10: Positive and Very Positive)\n\nThese are the sentiment levels of the Sift app. A record that is not analyzed (sentiment 0) is in no count.\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 7 days ago)\n- `to` - End date (ISO string, default: now)","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"Very Negative":{"type":"number"},"Negative":{"type":"number"},"Neutral":{"type":"number"},"Positive":{"type":"number"}},"required":["day","Very Negative","Negative","Neutral","Positive"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/analytics/sentiment/by-tag":{"get":{"summary":"Get sentiment breakdown by tag","tags":["v0"],"description":"Retrieve sentiment distribution for each tag.\n\n**Returns array of:**\n- `tagName` - Tag name\n- `veryNegative`, `negative`, `neutral`, `positive` - Counts, with the levels of `GET /analytics/sentiment`\n- `totalMentions` - Total count\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 7 days ago)\n- `to` - End date (ISO string, default: now)","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"tagName":{"type":"string"},"veryNegative":{"type":"number"},"negative":{"type":"number"},"neutral":{"type":"number"},"positive":{"type":"number"},"totalMentions":{"type":"number"}},"required":["tagName","veryNegative","negative","neutral","positive","totalMentions"],"additionalProperties":false}}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/analytics/engagement":{"get":{"summary":"Get user engagement metrics","tags":["v0"],"description":"Retrieve comprehensive user engagement analytics including:\n\n**Engagement Percentiles:**\n- Messages per user (p25, median, p75) by platform\n\n**Growth Trends:**\n- Week-over-week user growth by platform\n\n**Conversion Funnel:**\n- Active users → Analyzed users → Action users by platform\n\n**Query Parameters:**\n- `from` - Start date (ISO string, default: 7 days ago)\n- `to` - End date (ISO string, default: now)\n- `platforms` - Comma-separated platform filter (e.g., \"TWITTER,DISCORD\")","parameters":[{"schema":{},"in":"query","name":"from","required":false},{"schema":{},"in":"query","name":"to","required":false},{"schema":{"type":"string"},"in":"query","name":"platforms","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"engagementPercentiles":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"p25MessagesPerUser":{"type":"number"},"medianMessagesPerUser":{"type":"number"},"p75MessagesPerUser":{"type":"number"}},"required":["platform","p25MessagesPerUser","medianMessagesPerUser","p75MessagesPerUser"],"additionalProperties":false}},"growthTrends":{"type":"array","items":{"type":"object","properties":{"week":{"type":"string","format":"date-time"},"platform":{"type":"string"},"currentWeekUsers":{"type":"number"},"previousWeekUsers":{"type":"number"},"growthPercentage":{"type":"number"}},"required":["week","platform","currentWeekUsers","previousWeekUsers","growthPercentage"],"additionalProperties":false}},"conversionFunnel":{"type":"array","items":{"type":"object","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"}]}}}},"required":["engagementPercentiles","growthTrends","conversionFunnel"],"additionalProperties":false}},"required":["success","data"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/conversations/search":{"get":{"summary":"Search conversations","tags":["v0"],"description":"Search and filter conversations/threads using Advanced Search DSL.\n\n**Filter Syntax:**\n- `field=value` - equals\n- `field!=value` - not equals\n- `field>value` / `field<value` - comparisons\n- `field~value` - contains\n- `field=min..max` - range\n- `expr+expr` - AND\n- `expr|expr` - OR\n- `(expr)` - grouping\n\n**Fields:**\n- `kw` - keyword (full-text search)\n- `src` - source/platform (e.g., TWITTER, DISCORD)\n- `ch` - channel id (`ch~name` matches the channel name text)\n- `sent` - sentiment: a number from 1 to 10, or a level name (Very Negative 1-2, Negative 3-4, Neutral 5-6, Positive 7-8, Very Positive 9-10)\n- `tg` - tag id\n- `ca` - createdAt (date, supports relative: -7d, -1m)\n- `st` - status (OPEN, RESPONDED, CLOSED)\n- `q` - queue id\n\nWhen the filter does not bound `ca` (createdAt), the search reads the last 30 days. Each row has the fields of a `/action/list` row, plus `threadId`, `easyId` and `contributors`.\n\nA tag, channel or queue filter takes the id of the row, not its display name. A name is refused with a 400 that names the value.\n\n**Examples:**\n```\n?filter=kw~refund                        # Search for \"refund\" in content\n?filter=sent<4                           # Sentiment below 4\n?filter=kw~refund+sent<4                 # \"refund\" AND sentiment below 4\n?filter=ca>-7d+kw~cancel                 # Last 7 days AND keyword \"cancel\"\n?filter=(src=TWITTER|src=DISCORD)+st=OPEN # Twitter OR Discord, status OPEN\n?filter=sent=1..3                        # Sentiment range 1-3\n?filter=sent=Negative,\"Very Negative\"     # Negative or Very Negative (1-4)\n```","parameters":[{"schema":{"type":"string"},"in":"query","name":"filter","required":false},{"schema":{"default":1,"type":"integer","minimum":1,"maximum":10000},"in":"query","name":"page","required":false},{"schema":{"default":50,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false}],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"actionId":{"type":"string"},"actionTitle":{"type":"string"},"actionSummary":{"type":"string"},"status":{"type":"string"},"platform":{"type":"string"},"recordType":{"nullable":true,"type":"string"},"isPublicPost":{"type":"boolean"},"siftURL":{"type":"string"},"sourceURL":{"nullable":true,"type":"string"},"queue":{"nullable":true,"type":"string"},"initialQueue":{"nullable":true,"type":"string"},"sentiment":{"nullable":true,"description":"The sentiment level: Very Negative, Negative, Neutral, Positive or Very Positive. Null when the case is not analyzed.","type":"string"},"sentimentScore":{"nullable":true,"description":"The sentiment score, 1 to 10. 0 is not analyzed.","type":"number"},"moderation":{"nullable":true,"type":"string"},"assigneeName":{"nullable":true,"type":"string"},"assigneeEmail":{"nullable":true,"type":"string"},"assigneeUserId":{"nullable":true,"type":"string"},"assigneeRole":{"nullable":true,"type":"string"},"userName":{"type":"string"},"userUsername":{"type":"string"},"userId":{"type":"string"},"userEmail":{"nullable":true,"type":"string"},"userFollowerCount":{"nullable":true,"type":"number"},"createdAt":{"type":"string"},"updatedAt":{"nullable":true,"type":"string"},"initialMessageTime":{"nullable":true,"type":"string"},"initialResponseTime":{"nullable":true,"type":"string"},"closeTime":{"nullable":true,"type":"string"},"claimTime":{"nullable":true,"type":"string"},"firstResponseTime":{"nullable":true,"type":"string"},"handleTime":{"nullable":true,"type":"string"},"serverName":{"type":"string"},"channelName":{"type":"string"},"csatScore":{"nullable":true,"type":"string"},"csatFeedback":{"nullable":true,"type":"string"},"estimatedCSAT":{"nullable":true,"type":"number"},"totalMessages":{"nullable":true,"type":"number"},"totalUserMessages":{"nullable":true,"type":"number"},"totalAgentMessages":{"nullable":true,"type":"number"},"tags":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"group":{"type":"string"}},"required":["value","group"],"additionalProperties":false}},"closingTags":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"group":{"type":"string"}},"required":["value","group"],"additionalProperties":false}},"customFields":{"type":"object","additionalProperties":{}},"rootMessageText":{"nullable":true,"type":"string"},"conversationJson":{"nullable":true,"type":"string"},"threadId":{"type":"string"},"easyId":{"nullable":true,"type":"string"},"contributors":{"nullable":true,"type":"string"}},"required":["actionId","actionTitle","actionSummary","status","platform","recordType","isPublicPost","siftURL","sourceURL","queue","initialQueue","sentiment","sentimentScore","moderation","assigneeName","assigneeEmail","assigneeUserId","assigneeRole","userName","userUsername","userId","userEmail","userFollowerCount","createdAt","updatedAt","initialMessageTime","initialResponseTime","closeTime","claimTime","firstResponseTime","handleTime","serverName","channelName","csatScore","csatFeedback","estimatedCSAT","totalMessages","totalUserMessages","totalAgentMessages","tags","closingTags","customFields","rootMessageText","conversationJson","threadId","easyId","contributors"],"additionalProperties":false}},"totalRecords":{"type":"number"},"totalRecordsCapped":{"type":"boolean"},"currentPage":{"type":"number"},"pageSize":{"type":"number"},"totalPages":{"type":"number"}},"required":["success","data","totalRecords","totalRecordsCapped","currentPage","pageSize","totalPages"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}},"/v0/ingest/records":{"post":{"summary":"Ingest normalized records","tags":["v0"],"description":"Accepts a batch of records already mapped to Sift's normalized shape and ingests them asynchronously (store, create actions, synthesize). Idempotent per (org, platform, serverId, externalId). `records[].url` must be an absolute http or https URL. For platform CUSTOM_API, use the Custom API routes (422). Requires the write scope.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string","enum":["DISCORD","SLACK","GITHUB","ZENDESK","REDDIT","TELEGRAM","FACEBOOK_GROUP","TWITTER_COMMUNITY","SALESFORCE","FACEBOOK","TWITTER","THREADS","TIKTOK","INSTAGRAM","LINKEDIN","WHATSAPP","YOUTUBE","GAINSIGHT","APPSTORE","GOOGLE_PLAY","HIGHER_LOGIC","DISCOURSE","CUSTOM_FORM","CUSTOM_API","MODERATION_API","CHROME_WEB_STORE","CANNY"]},"serverId":{"type":"string","minLength":1},"serverName":{"type":"string","minLength":1},"channelId":{"type":"string"},"channelName":{"type":"string"},"processingLevel":{"type":"string","enum":["INSIGHTS","STATS_ONLY"]},"records":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string","minLength":1},"threadExternalId":{"type":"string"},"parentExternalId":{"type":"string"},"authorId":{"type":"string","minLength":1},"authorName":{"type":"string","minLength":1},"title":{"type":"string"},"body":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":5},"createdAt":{"type":"string","minLength":1},"url":{"type":"string"},"recordType":{"type":"string","minLength":1},"customFields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/schema0"}}},"required":["externalId","authorId","authorName","body","createdAt","recordType"]}}},"required":["platform","serverId","serverName","records"],"additionalProperties":false}}}},"security":[{"apiKey":[]}],"responses":{"202":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["accepted"]},"accepted":{"type":"number"}},"required":["status","accepted"],"additionalProperties":false}}}},"403":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"422":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"}},"required":["success","error"],"additionalProperties":false}}}}}}}},"tags":[{"name":"v0","description":"Initial version endpoints"}]}