{ "openapi": "3.1.0", "info": { "title": "BAI Analytics API", "version": "1.3.0", "description": "The BAI Analytics integration API: push feedback from your own systems into feedback groups, read back analysis results, trigger survey invites, and subscribe to webhook events.\n\nAuthenticate every call with an API key from the dashboard (Integrations Hub -> API Keys), passed as `Authorization: Bearer inpk_live_...`. Account management, survey building, and the analytics UI live in the BAI Analytics dashboard and are not part of this API.\n\nTwo naming vocabularies are served: the recommended one speaks `feedback_group` / `source` / `field` (matching the product), and the classic one speaks `survey_series` / `survey` / `question`. They hit the same handlers; new integrations should use the recommended routes. See the guides in this section for concepts, authentication, and webhook verification.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in each example \u2014 not the `{\"data\": ...}` wrapper the schemas declare. The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration only; they do not deprecate any endpoint.\n\nEvery write endpoint states the key permission it requires. Rate limits are per key, org, and IP \u2014 `GET /api/input/me` reports your effective limits, and windows are fixed: requests rejected with 429 never extend the wait announced in `Retry-After`.", "contact": { "name": "BAI Analytics Engineering", "email": "dev@boundary-ai.com" }, "license": { "name": "Proprietary - BAI Analytics Terms of Service", "url": "https://baianalytics.com/terms-and-conditions/" }, "termsOfService": "https://baianalytics.com/terms-and-conditions/", "x-public-spec-generated": true }, "servers": [ { "url": "https://app.boundary-ai.com", "description": "Production" } ], "tags": [ { "name": "Feedback groups & sources", "description": "Create the containers your data lands in: a **feedback group** holds everything about one programme, and each **source** inside it holds one stream of feedback with typed **fields**. Sources are created in draft mode; publish one to start pushing content." }, { "name": "Push feedback", "description": "Append feedback items to a source's field: single calls for steady trickles, bulk + async status for backfills, or a CSV/XLSX upload. Structured items support `external_id` dedup (retries never double-write), `occurred_at` back-dating, ratings, and per-item metadata." }, { "name": "Analysis", "description": "Read back what the platform found: sentiment distribution, themes, and Custom Monitoring matches for a source. Pair with the `analysis.completed` webhook instead of polling." }, { "name": "Invites", "description": "Trigger personalized survey-invite emails from the API using the template designed in the dashboard. Requires the `send` key permission and a verified sending domain." }, { "name": "Your data & privacy", "description": "List what you've pushed and erase it again \u2014 `POST /feedback/erase` handles GDPR erasure requests by `external_id` or `customer_id` for API-pushed rows." }, { "name": "API keys", "description": "Introspect the calling key: its permissions, effective rate limits, credit status, and the webhook events available for subscription." }, { "name": "Classic vocabulary (aliases)", "description": "The same operations in the original `survey_series` / `survey` / `question` naming. Fully supported and **not** deprecated \u2014 but new integrations should prefer the feedback-group routes above, which match the product's own vocabulary. A `survey_series` is a feedback group; a `survey` is a source; a `question` is a field." } ], "paths": { "/api/input/content/push": { "post": { "summary": "Push content rows to a question", "description": "Append free-text or typed content to one question on a survey via the customer's Input API key. Idempotent when an `Idempotency-Key` header is provided \u2014 duplicate keys with the same payload replay the original response within a 24h window.\n\n**Requires permission:** `push` or `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_post_content_push", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque client-supplied key for safe retries (24h window)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPushRequest" }, "example": { "survey_series_id": "1842", "survey_id": "9021", "question": { "question_id": "31245", "content": [ "The new dashboard is great, but exports are slow.", { "text": "Support resolved my issue in one call.", "external_id": "ticket-58121", "customer_id": "cus_310", "channel": "support", "language": "en", "rating": 5, "occurred_at": "2026-07-12T09:30:00Z" } ] } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ContentPushResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "survey_series_id": 1842, "survey_id": 9021, "question_id": 31245, "inserted": 2, "rows_accepted": 2, "aps_deducted": 2, "skipped_duplicates": 0, "duplicate_external_ids": [] } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment Required \u2014 insufficient credits / APS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (idempotency key reuse or resource conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "push", "create", "all" ] } }, "/api/input/content/push/bulk": { "post": { "summary": "Submit a bulk content push (async)", "description": "Queue a multi-question content batch for async processing. Returns 202 with a `task_id` and `status_url` \u2014 poll the status endpoint for the final result. Idempotent via `Idempotency-Key` header (24h window).\n\n**Requires permission:** `push` or `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_post_content_push_bulk", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque retry key (24h window)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkContentPushRequest" }, "example": { "survey_series_id": "1842", "survey_id": "9021", "questions": [ { "question_id": "31245", "content": [ "First comment", "Second comment" ] }, { "question_id": "31246", "content": [ { "text": "9", "external_id": "rev-4471" } ] } ] } } } }, "responses": { "202": { "description": "Accepted \u2014 task queued for async processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkPushAccepted" } }, "required": [ "data" ] }, "example": { "status": "accepted", "task_id": "3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11", "survey_series_id": 1842, "survey_id": 9021, "status_url": "/api/input/content/push/bulk/status/3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (idempotency key reuse or resource conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "push", "create", "all" ] } }, "/api/input/content/push/bulk/status/{task_id}": { "get": { "summary": "Poll the status of a bulk content push", "description": "Returns 202 while pending/processing, 200 on completed or failed (the discriminator is the `status` field, not the HTTP code, so the success-vs-recorded-failure path stays machine-readable). 404 when the task id is unknown for the calling org.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_get_content_push_bulk_status", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkPushStatus" } }, "required": [ "data" ] }, "example": { "task_id": "3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11", "status": "completed", "progress": 100, "progress_message": "Inserted 2400 items", "created_at": "2026-07-12T09:31:02Z", "completed_at": "2026-07-12T09:31:44Z", "survey_series_id": 1842, "survey_id": 9021, "result": { "status": "success", "survey_series_id": 1842, "survey_id": 9021, "total_inserted": 2400, "total_rows_accepted": 2412, "total_aps_deducted": 2412, "questions": [ { "question_id": 31245, "inserted": 2398, "status": "success" }, { "question_id": 31246, "inserted": 2, "status": "success" } ] } } } } }, "202": { "description": "Accepted \u2014 task queued for async processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkPushStatus" } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/feedback": { "get": { "summary": "List pushed feedback items (cursor-paginated)", "description": "Keyset-paginated listing of items the Input API ingested for this org (never native survey responses). Filter by `source_id` and/or `field_id`; pass the returned `next_cursor` back as `cursor` to fetch the next page. Ordered by item id ascending, so pages are stable while new items land.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Your data & privacy" ], "operationId": "inputapi_get_feedback", "parameters": [ { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "field_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from the previous page's next_cursor" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeedbackListResponse" } }, "required": [ "data" ] }, "example": { "items": [ { "id": 88123, "source_id": 9021, "field_id": 31245, "type": "text", "text": "Support resolved my issue in one call.", "numeric": null, "external_id": "ticket-58121", "metadata": null, "source_reference": "crm-sync", "occurred_at": "2026-07-12T09:30:00Z" } ], "next_cursor": "88123", "has_more": true } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/feedback/erase": { "post": { "summary": "Bulk-erase pushed feedback (erasure requests)", "description": "Deletes items the Input API ingested, selected by `external_ids` (item-level) or `customer_id` (erases every item whose ingest metadata carries that customer \u2014 the GDPR erasure shape). Exactly one selector is required; `feedback_group_id` optionally narrows the scope. Only API-pushed rows are ever touched. Existing analyses are not rewritten retroactively \u2014 they drop the erased items on their next run.\n\n**Requires permission:** `push` or `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Your data & privacy" ], "operationId": "inputapi_post_feedback_erase", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque retry key (24h window)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EraseFeedbackRequest" }, "example": { "external_ids": [ "ticket-58121", "rev-4471" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EraseFeedbackResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "deleted": 2, "sources_affected": 1, "message": "Deleted 2 item(s) across 1 source(s)" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "push", "create", "all" ] } }, "/api/input/feedback/push": { "post": { "summary": "Push feedback items to a field", "description": "Partner-vocabulary variant of `/content/push`: append feedback items to one field on a source. Accepts the same payload with `feedback_group_id` / `source_id` / `field.field_id` naming and responds in the same vocabulary. Idempotent via the `Idempotency-Key` header (24h window).\n\n**Requires permission:** `push` or `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Push feedback" ], "operationId": "inputapi_post_feedback_push", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque client-supplied key for safe retries (24h window)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackPushRequest" }, "example": { "feedback_group_id": "1842", "source_id": "9021", "field": { "field_id": "31245", "content": [ "The new dashboard is great, but exports are slow.", { "text": "Support resolved my issue in one call.", "external_id": "ticket-58121", "customer_id": "cus_310", "channel": "support", "language": "en", "rating": 5, "occurred_at": "2026-07-12T09:30:00Z" } ] } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeedbackPushResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "feedback_group_id": 1842, "source_id": 9021, "field_id": 31245, "inserted": 2, "rows_accepted": 2, "aps_deducted": 2, "skipped_duplicates": 0, "duplicate_external_ids": [] } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Payment Required \u2014 insufficient credits / APS", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (idempotency key reuse or resource conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "push", "create", "all" ] } }, "/api/input/feedback/push/bulk": { "post": { "summary": "Submit a bulk feedback push (async)", "description": "Partner-vocabulary variant of `/content/push/bulk`: queue a multi-field feedback batch for async processing. Returns 202 with a `task_id` and partner-path `status_url`. Idempotent via `Idempotency-Key` header (24h window).\n\n**Requires permission:** `push` or `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Push feedback" ], "operationId": "inputapi_post_feedback_push_bulk", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque retry key (24h window)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkFeedbackPushRequest" }, "example": { "feedback_group_id": "1842", "source_id": "9021", "fields": [ { "field_id": "31245", "content": [ "First comment", "Second comment" ] }, { "field_id": "31246", "content": [ { "text": "9", "external_id": "rev-4471" } ] } ] } } } }, "responses": { "202": { "description": "Accepted \u2014 task queued for async processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkFeedbackPushAccepted" } }, "required": [ "data" ] }, "example": { "status": "accepted", "task_id": "3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11", "feedback_group_id": 1842, "source_id": 9021, "status_url": "/api/input/feedback/push/bulk/status/3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (idempotency key reuse or resource conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "push", "create", "all" ] } }, "/api/input/feedback/push/bulk/status/{task_id}": { "get": { "summary": "Poll the status of a bulk feedback push", "description": "Partner-vocabulary variant of `/content/push/bulk/status/{task_id}`. 202 while pending/processing, 200 on completed or failed (the `status` field is the discriminator). 404 when the task id is unknown for the calling org.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Push feedback" ], "operationId": "inputapi_get_feedback_push_bulk_status", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkFeedbackPushStatus" } }, "required": [ "data" ] }, "example": { "task_id": "3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11", "status": "completed", "progress": 100, "progress_message": "Inserted 2400 items", "created_at": "2026-07-12T09:31:02Z", "completed_at": "2026-07-12T09:31:44Z", "feedback_group_id": 1842, "source_id": 9021, "result": { "status": "success", "feedback_group_id": 1842, "source_id": 9021, "total_inserted": 2400, "total_rows_accepted": 2412, "total_aps_deducted": 2412, "fields": [ { "field_id": 31245, "inserted": 2398, "status": "success" }, { "field_id": 31246, "inserted": 2, "status": "success" } ] } } } } }, "202": { "description": "Accepted \u2014 task queued for async processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkFeedbackPushStatus" } }, "required": [ "data" ] } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/feedback/upload": { "post": { "summary": "Upload a CSV/XLSX of feedback (async ingest)", "description": "Multipart upload: `file` (.csv or .xlsx) plus `feedback_group_id`, `source_id` and `field_id` form fields. The text column is picked with `column` (header name; defaults to the first column). Optional `_column` fields (external_id_column, customer_id_column, channel_column, language_column, rating_column, occurred_at_column) map spreadsheet columns onto the structured ingest metadata, including external-ID dedup. Returns 202 with a `task_id`; poll the bulk status endpoint. Idempotent via the `Idempotency-Key` header (24h window) \u2014 a retried upload of the same file replays the original 202 instead of re-ingesting the rows.\n\n**Requires permission:** `push` or `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Push feedback" ], "operationId": "inputapi_post_feedback_upload", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque client-supplied key for safe retries (24h window)." } ], "responses": { "202": { "description": "Accepted \u2014 task queued for async processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/BulkFeedbackPushAccepted" } }, "required": [ "data" ] }, "example": { "status": "accepted", "task_id": "3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11", "feedback_group_id": 1842, "source_id": 9021, "rows_submitted": 2400, "status_url": "/api/input/feedback/push/bulk/status/3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Payload Too Large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "push", "create", "all" ] } }, "/api/input/feedback_groups/create": { "post": { "summary": "Create a feedback group", "description": "Partner-vocabulary variant of `/survey_series/create`. Idempotent on group name within the org \u2014 if a group with the same name already exists, returns 200 with `created: false` and the existing group id.\n\n**Requires permission:** `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Feedback groups & sources" ], "operationId": "inputapi_post_feedback_groups_create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateFeedbackGroupRequest" }, "example": { "name": "Customer Support EU" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateFeedbackGroupResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "created": false, "message": "Survey series already exists", "feedback_group": { "id": 1842, "name": "Customer Support EU" } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateFeedbackGroupResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "created": true, "feedback_group": { "id": 1842, "name": "Customer Support EU" } } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "all" ] } }, "/api/input/invites/{distribution_id}": { "get": { "summary": "Get an invite distribution's status", "description": "Lifecycle + counts for one API-triggered send. `status` is the discriminator: pending/sending are in flight; sent/partial/failed are terminal. Subscribe to the `invites.completed` webhook event instead of polling.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Invites" ], "operationId": "inputapi_get_invite_distribution", "parameters": [ { "name": "distribution_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InviteDistributionStatus" } }, "required": [ "data" ] }, "example": { "distribution_id": 7301, "survey_id": 9021, "status": "sent", "total": 1000, "sent": 991, "failed": 4, "skipped": 5, "created_at": "2026-07-12T10:00:00Z", "finished_at": "2026-07-12T10:06:31Z" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/invites/{distribution_id}/recipients": { "get": { "summary": "List a distribution's recipients (cursor-paginated)", "description": "Per-recipient outcomes: send status, ESP delivery status (populated asynchronously from delivery events), and your `external_id` for correlation. Pass `next_cursor` back as `cursor` for the next page.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Invites" ], "operationId": "inputapi_get_invite_recipients", "parameters": [ { "name": "distribution_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InviteRecipientsPage" } }, "required": [ "data" ] }, "example": { "items": [ { "id": 1, "email": "jamie@example.com", "external_id": "cus_310", "status": "sent", "delivery_status": "delivered", "error": null } ], "next_cursor": null, "has_more": false } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/me": { "get": { "summary": "Self-serve info about the calling API key", "description": "Returns the key's own public fields (name, environment, permissions), the effective rate limits, the org's credit status, and the webhook event types available for subscriptions \u2014 so an integration can introspect its own capabilities without dashboard access.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "API keys" ], "operationId": "inputapi_get_me", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/KeySelfInfoResponse" } }, "required": [ "data" ] }, "example": { "key": { "id": 77, "key_id": "k7jq3v9d2m", "display_key": "inpk_live_...x4X2b9", "key_suffix": "x4X2b9", "name": "CRM sync (production)", "environment": "live", "permissions": "push", "rate_limit_per_minute": 60, "is_active": true, "org_id": 412, "description": null, "created_at": "2026-06-01T09:00:00+00:00", "last_used_at": "2026-07-12T09:30:05+00:00", "revoked_at": null }, "org_id": 412, "rate_limits": { "per_key_per_minute": 60, "per_org_per_minute": 300, "per_ip_per_minute": 600, "window_seconds": 60 }, "credits": { "limit": 10000, "used": 2411.5, "remaining": 7588.5, "period_start": "2026-07-01T00:00:00+00:00", "period_end": "2026-08-01T00:00:00+00:00", "rate_tokens_per_aps": 5000 }, "webhook_events": [ "content.pushed", "survey.created", "survey.published", "series.created", "analysis.completed", "flag.raised", "report.ready", "invites.completed", "invite.bounced" ] } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/sources/create": { "post": { "summary": "Create a source inside a feedback group", "description": "Partner-vocabulary variant of `/survey/create`. Creates a new source in EDITING mode with the supplied fields; not publicly accessible until `/sources/publish` is called. Field types are case-insensitive.\n\n**Requires permission:** `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Feedback groups & sources" ], "operationId": "inputapi_post_sources_create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceRequest" }, "example": { "feedback_group_id": "1842", "source_title": "Support tickets (CRM sync)", "source_description": "Tickets pushed nightly from our CRM", "feedback_type": "support_ticket", "language": "en", "fields": [ { "field_title": "What was the issue?", "field_type": "DEPTH_TEXT" }, { "field_title": "How likely are you to recommend us?", "field_type": "NPS" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateSourceResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "feedback_group_id": 1842, "source_id": 9021, "feedback_type": "support_ticket", "fields_created": 2, "fields": [ { "id": 31245, "title": "What was the issue?", "type": "DEPTH_TEXT" }, { "id": 31246, "title": "How likely are you to recommend us?", "type": "NPS" } ], "message": "Source 'Support tickets (CRM sync)' created with 2 field(s)" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "create", "all" ] } }, "/api/input/sources/list": { "get": { "summary": "List sources accessible to the API key's organization", "description": "Partner-vocabulary variant of `/surveys/list`: feedback groups with their sources and fields, including `accepts_content`, `content_format` and `mode`. Filterable by `feedback_group_id` and `source_id`; paginated at the feedback-group level via `limit`/`offset`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Feedback groups & sources" ], "operationId": "inputapi_get_sources_list", "parameters": [ { "name": "feedback_group_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Max feedback groups returned per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of feedback groups to skip." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SourcesListResponse" } }, "required": [ "data" ] }, "example": { "feedback_groups": [ { "id": 1842, "name": "Customer Support EU", "sources": [ { "id": 9021, "title": "Support tickets (CRM sync)", "description": "Tickets pushed nightly from our CRM", "mode": "ACCESSIBLE", "feedback_type": "support_ticket", "fields": [ { "id": 31245, "title": "What was the issue?", "type": "DEPTH_TEXT" } ] } ] } ], "pagination": { "limit": 50, "offset": 0, "total_count": 1 } } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/sources/publish": { "post": { "summary": "Publish a source (move to ACCESSIBLE mode)", "description": "Partner-vocabulary variant of `/survey/publish`. Idempotent: publishing an already-ACCESSIBLE source is a no-op that returns 200 with the same shape.\n\n**Requires permission:** `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Feedback groups & sources" ], "operationId": "inputapi_post_sources_publish", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishSourceRequest" }, "example": { "source_id": 9021, "feedback_group_id": 1842 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublishSourceResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "source_id": 9021, "feedback_group_id": 1842, "mode": "ACCESSIBLE", "message": "Source published successfully" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "create", "all" ] } }, "/api/input/sources/{survey_id}/analysis": { "get": { "summary": "Read processed analysis for a source", "description": "Partner-vocabulary variant of `/surveys/{survey_id}/analysis`: sentiment distribution, themes and monitored flags for one source. Flags are monitored at the feedback-group level. Analysis launches automatically after content lands and takes minutes to tens of minutes depending on volume and queue depth; `analysis_status: \"none\"` means no completed run has been persisted yet (it does not distinguish queued from in-progress). Pair with the `analysis.completed` webhook \u2014 registered in the dashboard's Integrations Hub \u2014 instead of polling.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Analysis" ], "operationId": "inputapi_get_source_analysis", "parameters": [ { "name": "survey_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "The source id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SourceAnalysisReadResponse" } }, "required": [ "data" ] }, "example": { "source_id": 9021, "feedback_group_id": 1842, "feedback_type": "support_ticket", "analysis_id": 55710, "analysis_status": "available", "sentiment_distribution": { "veryPositive": 312, "positive": 540, "neutral": 205, "negative": 118, "veryNegative": 42 }, "themes": [ { "name": "Response time", "mentions": 214, "avg_sentiment": -0.31, "description": "Waiting time before the first reply" } ], "flags": [ { "name": "Churn risk", "mentions": 17, "avg_sentiment": -0.62, "summary": "Accounts describing an intent to cancel", "scope": "survey_series" } ] } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/sources/{survey_id}/invite-template": { "get": { "summary": "Inspect the source's invite template + sending readiness", "description": "What an integration needs before calling the send endpoint: whether a template is configured in the platform, which variable keys it can personalize with, whether the org's sender domain is verified (required for API sends), and the current daily quota usage.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Invites" ], "operationId": "inputapi_get_source_invite_template", "parameters": [ { "name": "survey_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "The source id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InviteTemplateInfo" } }, "required": [ "data" ] }, "example": { "configured": true, "subject": "How did we do, {{first_name}}?", "variables": [ "first_name", "order_id" ], "sender_domain_verified": true, "sending_enabled": true, "daily_quota": 2000, "daily_quota_used": 150 } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/sources/{survey_id}/invites": { "post": { "summary": "Send survey invites by email (transactional)", "description": "Emails the survey to the supplied recipients using the invite template designed in the platform. Recipients are appended to the source's respondent list (each gets a personalized survey link, so responses join back to the contact). Addresses that already received this survey are skipped unless `resend` is true; suppressed addresses (unsubscribed / bounced) are never emailed. Requires a `send`-scoped API key AND the org's own verified sending domain \u2014 the shared BAI Analytics sender is reserved for dashboard sends. Set `dry_run` to preview the rendered emails without sending. Returns 202 + a `distribution_id` to poll; subscribe to `invites.completed` and `invite.bounced` webhook events for the outcomes.\n\n**Requires permission:** `send` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Invites" ], "operationId": "inputapi_post_source_invites", "parameters": [ { "name": "survey_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" }, "description": "The source id" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Opaque retry key (24h window). Strongly recommended for send calls." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendInvitesRequest" }, "example": { "recipients": [ { "email": "jamie@example.com", "external_id": "cus_310", "variables": { "first_name": "Jamie", "order_id": "A-1042" } } ], "resend": false, "dry_run": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendInvitesDryRun" } }, "required": [ "data" ] } } } }, "202": { "description": "Accepted \u2014 task queued for async processing", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SendInvitesAccepted" } }, "required": [ "data" ] }, "example": { "status": "accepted", "distribution_id": 7301, "task_id": "3fa2b7c8-6d1e-4f90-9a55-0c8e2d7b4a11", "accepted": 1, "skipped_already_invited": [], "invalid": [], "status_url": "/api/input/invites/7301" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict (idempotency key reuse or resource conflict)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate Limited \u2014 see Retry-After header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "send", "all" ] } }, "/api/input/survey/create": { "post": { "summary": "Create a survey inside a series", "description": "Creates a new survey in EDITING mode with the supplied questions. The survey is not publicly accessible until `/survey/publish` is called. Question types are case-insensitive.\n\n**Requires permission:** `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_post_survey_create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSurveyRequest" }, "example": { "survey_series_id": "1842", "survey_title": "Support tickets (CRM sync)", "survey_description": "Tickets pushed nightly from our CRM", "feedback_type": "support_ticket", "language": "en", "questions": [ { "question_title": "What was the issue?", "question_type": "DEPTH_TEXT" }, { "question_title": "How likely are you to recommend us?", "question_type": "NPS" } ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateSurveyResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "survey_series_id": 1842, "survey_id": 9021, "feedback_type": "support_ticket", "questions_created": 2, "questions": [ { "id": 31245, "title": "What was the issue?", "type": "DEPTH_TEXT" }, { "id": 31246, "title": "How likely are you to recommend us?", "type": "NPS" } ], "message": "Survey 'Support tickets (CRM sync)' created with 2 question(s)" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "create", "all" ] } }, "/api/input/survey/publish": { "post": { "summary": "Publish a survey (move to ACCESSIBLE mode)", "description": "Idempotent: publishing an already-ACCESSIBLE survey is a no-op that returns 200 with the same shape.\n\n**Requires permission:** `create` or `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_post_survey_publish", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishSurveyRequest" }, "example": { "survey_id": 9021, "survey_series_id": 1842 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublishSurveyResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "survey_id": 9021, "survey_series_id": 1842, "mode": "ACCESSIBLE", "message": "Survey published successfully" } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "create", "all" ] } }, "/api/input/survey_series/create": { "post": { "summary": "Create a survey series", "description": "Idempotent on series name within the org \u2014 if a series with the same name already exists, returns 200 with `created: false` and the existing series id.\n\n**Requires permission:** `all`.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_post_survey_series_create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSurveySeriesRequest" }, "example": { "name": "Customer Support EU" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateSurveySeriesResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "created": false, "message": "Survey series already exists", "survey_series": { "id": 1842, "name": "Customer Support EU" } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreateSurveySeriesResponse" } }, "required": [ "data" ] }, "example": { "status": "success", "created": true, "survey_series": { "id": 1842, "name": "Customer Support EU" } } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ], "x-required-permission": [ "all" ] } }, "/api/input/surveys/list": { "get": { "summary": "List surveys accessible to the API key's organization", "description": "API-key-authenticated variant \u2014 exposes extended fields (`accepts_content`, `content_format`, `mode`) that the Clerk variant omits, for CLI / integration usage.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_get_surveys_list", "parameters": [ { "name": "survey_series_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "survey_id", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Max survey series returned per page." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Number of series to skip (series-level pagination)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SurveysListResponse" } }, "required": [ "data" ] }, "example": { "survey_series": [ { "id": 1842, "name": "Customer Support EU", "surveys": [ { "id": 9021, "title": "Support tickets (CRM sync)", "description": "Tickets pushed nightly from our CRM", "mode": "ACCESSIBLE", "feedback_type": "support_ticket", "questions": [ { "id": 31245, "title": "What was the issue?", "type": "DEPTH_TEXT" } ] } ] } ], "pagination": { "limit": 50, "offset": 0, "total_count": 1 } } } } }, "400": { "description": "Bad Request \u2014 validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } }, "/api/input/surveys/{survey_id}/analysis": { "get": { "summary": "Read processed analysis for a survey", "description": "The read half of the API: pull sentiment distribution, themes and monitored flags back out once analysis has run on pushed feedback. Flags are monitored at the feedback-group level, so the `flags` list covers the whole group this survey belongs to. Analysis launches automatically after content lands and takes minutes to tens of minutes depending on volume and queue depth; `analysis_status: \"none\"` means no completed run has been persisted yet (it does not distinguish queued from in-progress). Pair with the `analysis.completed` webhook \u2014 registered in the dashboard's Integrations Hub \u2014 instead of polling.\n\n**Response envelope migration:** during the current migration window, 2xx responses carry the bare payload shown in the example (the value of the schema's `data` property, without the `{\"data\": ...}` wrapper). The `Deprecation` and `Sunset` headers on every 2xx announce this envelope migration \u2014 they do **not** deprecate the endpoint itself. After the `Sunset` date, responses will be wrapped as `{\"data\": ...}` exactly as the schema declares.", "tags": [ "Classic vocabulary (aliases)" ], "operationId": "inputapi_get_survey_analysis", "parameters": [ { "name": "survey_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SurveyAnalysisReadResponse" } }, "required": [ "data" ] }, "example": { "survey_id": 9021, "survey_series_id": 1842, "feedback_type": "support_ticket", "analysis_id": 55710, "analysis_status": "available", "sentiment_distribution": { "veryPositive": 312, "positive": 540, "neutral": 205, "negative": 118, "veryNegative": 42 }, "themes": [ { "name": "Response time", "mentions": 214, "avg_sentiment": -0.31, "description": "Waiting time before the first reply" } ], "flags": [ { "name": "Churn risk", "mentions": 17, "avg_sentiment": -0.62, "summary": "Accounts describing an intent to cancel", "scope": "survey_series" } ] } } } }, "401": { "description": "Unauthorized \u2014 missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden \u2014 insufficient permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "apiKeyAuth": [] } ] } } }, "components": { "schemas": { "ContentPushedData": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "question_id": { "title": "Question Id", "type": "integer" }, "original_survey_id": { "title": "Original Survey Id", "type": "integer" }, "original_question_id": { "title": "Original Question Id", "type": "integer" }, "lines_pushed": { "minimum": 0, "title": "Lines Pushed", "type": "integer" }, "api_key_id": { "title": "Api Key Id", "type": "integer" } }, "required": [ "survey_series_id", "survey_id", "question_id", "original_survey_id", "original_question_id", "lines_pushed", "api_key_id" ], "title": "ContentPushedData", "type": "object" }, "ContentPushedEvent": { "additionalProperties": false, "properties": { "event": { "const": "content.pushed", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/ContentPushedData" } }, "required": [ "event", "timestamp", "data" ], "title": "ContentPushedEvent", "type": "object" }, "SeriesCreatedData": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "api_key_id": { "title": "Api Key Id", "type": "integer" } }, "required": [ "survey_series_id", "name", "api_key_id" ], "title": "SeriesCreatedData", "type": "object" }, "SeriesCreatedEvent": { "additionalProperties": false, "properties": { "event": { "const": "series.created", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/SeriesCreatedData" } }, "required": [ "event", "timestamp", "data" ], "title": "SeriesCreatedEvent", "type": "object" }, "SurveyCreatedData": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "survey_title": { "title": "Survey Title", "type": "string" }, "questions_created": { "minimum": 0, "title": "Questions Created", "type": "integer" }, "api_key_id": { "title": "Api Key Id", "type": "integer" } }, "required": [ "survey_series_id", "survey_id", "survey_title", "questions_created", "api_key_id" ], "title": "SurveyCreatedData", "type": "object" }, "SurveyCreatedEvent": { "additionalProperties": false, "properties": { "event": { "const": "survey.created", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/SurveyCreatedData" } }, "required": [ "event", "timestamp", "data" ], "title": "SurveyCreatedEvent", "type": "object" }, "SurveyPublishedData": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "survey_name": { "title": "Survey Name", "type": "string" }, "api_key_id": { "title": "Api Key Id", "type": "integer" } }, "required": [ "survey_series_id", "survey_id", "survey_name", "api_key_id" ], "title": "SurveyPublishedData", "type": "object" }, "SurveyPublishedEvent": { "additionalProperties": false, "properties": { "event": { "const": "survey.published", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/SurveyPublishedData" } }, "required": [ "event", "timestamp", "data" ], "title": "SurveyPublishedEvent", "type": "object" }, "AnalysisCompletedData": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "analysis_id": { "title": "Analysis Id", "type": "integer" }, "survey_name": { "title": "Survey Name", "type": "string" } }, "required": [ "survey_series_id", "survey_id", "analysis_id", "survey_name" ], "title": "AnalysisCompletedData", "type": "object" }, "AnalysisCompletedEvent": { "additionalProperties": false, "properties": { "event": { "const": "analysis.completed", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/AnalysisCompletedData" } }, "required": [ "event", "timestamp", "data" ], "title": "AnalysisCompletedEvent", "type": "object" }, "FlagRaisedData": { "description": "Fired when a Custom Monitoring monitor crosses its alert threshold.\n\nThe event name keeps the legacy ``flag`` wording for backward\ncompatibility with existing subscribers; in product vocabulary this\nis a *monitor* alert. It fires under the same watermark/threshold\ngate as email/SMS monitor alerts.", "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "analysis_id": { "title": "Analysis Id", "type": "integer" }, "survey_name": { "title": "Survey Name", "type": "string" }, "group_name": { "description": "The feedback group's name", "title": "Group Name", "type": "string" }, "trigger_type": { "title": "Trigger Type", "type": "string" }, "flag_counts": { "additionalProperties": { "type": "integer" }, "description": "Monitor name -> count of NEW matches since the last alert", "title": "Flag Counts", "type": "object" }, "total_flagged": { "minimum": 0, "title": "Total Flagged", "type": "integer" } }, "required": [ "survey_series_id", "survey_id", "analysis_id", "survey_name", "group_name", "trigger_type", "flag_counts", "total_flagged" ], "title": "FlagRaisedData", "type": "object" }, "FlagRaisedEvent": { "additionalProperties": false, "properties": { "event": { "const": "flag.raised", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/FlagRaisedData" } }, "required": [ "event", "timestamp", "data" ], "title": "FlagRaisedEvent", "type": "object" }, "ReportReadyData": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "subscription_id": { "title": "Subscription Id", "type": "integer" }, "period_key": { "description": "The closed tracking period the report covers", "title": "Period Key", "type": "string" }, "report_id": { "title": "Report Id", "type": "integer" }, "report_name": { "title": "Report Name", "type": "string" } }, "required": [ "survey_series_id", "subscription_id", "period_key", "report_id", "report_name" ], "title": "ReportReadyData", "type": "object" }, "ReportReadyEvent": { "additionalProperties": false, "properties": { "event": { "const": "report.ready", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/ReportReadyData" } }, "required": [ "event", "timestamp", "data" ], "title": "ReportReadyEvent", "type": "object" }, "InvitesCompletedData": { "properties": { "distribution_id": { "title": "Distribution Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "status": { "title": "Status", "type": "string" }, "total": { "minimum": 0, "title": "Total", "type": "integer" }, "sent": { "minimum": 0, "title": "Sent", "type": "integer" }, "failed": { "minimum": 0, "title": "Failed", "type": "integer" }, "skipped": { "minimum": 0, "title": "Skipped", "type": "integer" } }, "required": [ "distribution_id", "survey_id", "status", "total", "sent", "failed", "skipped" ], "title": "InvitesCompletedData", "type": "object" }, "InvitesCompletedEvent": { "additionalProperties": false, "properties": { "event": { "const": "invites.completed", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/InvitesCompletedData" } }, "required": [ "event", "timestamp", "data" ], "title": "InvitesCompletedEvent", "type": "object" }, "InviteBouncedData": { "properties": { "distribution_id": { "title": "Distribution Id", "type": "integer" }, "survey_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Survey Id" }, "email": { "title": "Email", "type": "string" }, "reason": { "description": "Bounce/suppression reason, e.g. \"bounce\" or \"complaint\"", "title": "Reason", "type": "string" } }, "required": [ "distribution_id", "email", "reason" ], "title": "InviteBouncedData", "type": "object" }, "InviteBouncedEvent": { "additionalProperties": false, "properties": { "event": { "const": "invite.bounced", "title": "Event", "type": "string" }, "timestamp": { "description": "ISO-8601 UTC timestamp", "title": "Timestamp", "type": "string" }, "data": { "$ref": "#/components/schemas/InviteBouncedData" } }, "required": [ "event", "timestamp", "data" ], "title": "InviteBouncedEvent", "type": "object" }, "ErrorObject": { "description": "The inner ``error`` field of an error envelope.\n\nSchema name in the OpenAPI document: ``ErrorObject``.", "example": { "code": "VALIDATION_ERROR", "message": "Invalid email address" }, "properties": { "code": { "description": "Machine-readable error code drawn from ErrorCode enum", "examples": [ "VALIDATION_ERROR" ], "title": "Code", "type": "string" }, "message": { "description": "Human-readable error message, safe to display", "examples": [ "Invalid email address" ], "title": "Message", "type": "string" } }, "required": [ "code", "message" ], "title": "ErrorObject", "type": "object" }, "ErrorEnvelope": { "description": "Top-level error response.\n\nSchema name in the OpenAPI document: ``ErrorEnvelope``.", "example": { "details": { "field": "email" }, "error": { "code": "VALIDATION_ERROR", "message": "Invalid email address" } }, "properties": { "error": { "$ref": "#/components/schemas/ErrorObject" }, "details": { "anyOf": [ {}, { "type": "null" } ], "default": null, "description": "Optional structured details (e.g. validation field map)", "title": "Details" } }, "required": [ "error" ], "title": "ErrorEnvelope", "type": "object" }, "ContentItem": { "description": "Structured content entry with ingest metadata.\n\nContent arrays accept bare strings (the original shape) or these\nobjects. ``external_id`` is the customer-side id used for\nupsert-dedup on retries; ``occurred_at`` back-dates the item for\nperiod bucketing; the rest is stored as structured context.", "example": { "channel": "app_store", "customer_id": "cus_1932", "external_id": "review-98421", "language": "en", "occurred_at": "2026-07-01T09:30:00Z", "rating": 2, "text": "App keeps crashing on checkout" }, "properties": { "text": { "description": "The feedback text", "minLength": 1, "title": "Text", "type": "string" }, "external_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Customer-side id of this item (ticket id, review id\u2026). Items whose (question, external_id) already exist are skipped, so retries never create duplicates.", "title": "External Id" }, "customer_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Customer Id" }, "channel": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "default": null, "title": "Channel" }, "language": { "anyOf": [ { "maxLength": 35, "type": "string" }, { "type": "null" } ], "default": null, "description": "BCP-47-ish language tag", "title": "Language" }, "rating": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "Numeric score attached to the item (e.g. review stars)", "title": "Rating" }, "occurred_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 timestamp of when the feedback happened (defaults to push time)", "title": "Occurred At" } }, "required": [ "text" ], "title": "ContentItem", "type": "object" }, "QuestionContentPush": { "example": { "content": [ "Customer feedback line 1", { "external_id": "ticket-1", "text": "Structured line" } ], "question_id": "12345" }, "properties": { "question_id": { "description": "Target question id (integer as string)", "title": "Question Id", "type": "string" }, "content": { "description": "Feedback entries \u2014 bare strings or structured items with ingest metadata", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentItem" } ] }, "minItems": 1, "title": "Content", "type": "array" } }, "required": [ "question_id", "content" ], "title": "QuestionContentPush", "type": "object" }, "ContentPushRequest": { "properties": { "survey_series_id": { "description": "Target survey series id", "title": "Survey Series Id", "type": "string" }, "survey_id": { "description": "Target survey id within the series", "title": "Survey Id", "type": "string" }, "question": { "$ref": "#/components/schemas/QuestionContentPush" }, "source_reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-form identifier the customer attaches to the push for their own downstream tracking (e.g. an upstream ticket id).", "title": "Source Reference" } }, "required": [ "survey_series_id", "survey_id", "question" ], "title": "ContentPushRequest", "type": "object" }, "ContentPushResponse": { "description": "Success body of POST /api/input/content/push.", "example": { "aps_deducted": 12, "duplicate_external_ids": [], "inserted": 12, "question_id": 100, "rows_accepted": 12, "skipped_duplicates": 0, "status": "success", "survey_id": 42, "survey_series_id": 7 }, "properties": { "status": { "const": "success", "description": "Always 'success' on this path", "title": "Status", "type": "string" }, "survey_series_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Series the resolved survey belongs to", "title": "Survey Series Id" }, "survey_id": { "description": "Resolved survey id where content landed", "title": "Survey Id", "type": "integer" }, "question_id": { "description": "Resolved question id where content landed", "title": "Question Id", "type": "integer" }, "inserted": { "description": "Number of content rows inserted", "minimum": 0, "title": "Inserted", "type": "integer" }, "rows_accepted": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Rows admitted for processing (inserted + skipped duplicates)", "title": "Rows Accepted" }, "aps_deducted": { "description": "Legacy alias of rows_accepted. Under token-based billing no APS is pre-deducted at push time \u2014 actual credit usage is metered during analysis, and test-environment keys are never charged. A fully-deduplicated retry still reports its admitted row count here.", "minimum": 0, "title": "Aps Deducted", "type": "integer" }, "skipped_duplicates": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Rows skipped because their (question, external_id) already existed", "title": "Skipped Duplicates" }, "duplicate_external_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "description": "External ids of the skipped rows (first 100)", "title": "Duplicate External Ids" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Human-readable confirmation", "title": "Message" } }, "required": [ "status", "survey_id", "question_id", "inserted", "aps_deducted" ], "title": "ContentPushResponse", "type": "object" }, "FieldContentPush": { "properties": { "field_id": { "description": "Target field id (integer as string)", "title": "Field Id", "type": "string" }, "content": { "description": "Feedback items \u2014 bare strings or structured items with ingest metadata", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentItem" } ] }, "minItems": 1, "title": "Content", "type": "array" } }, "required": [ "field_id", "content" ], "title": "FieldContentPush", "type": "object" }, "FeedbackPushRequest": { "example": { "feedback_group_id": "7", "field": { "content": [ "Customer feedback line 1" ], "field_id": "100" }, "source_id": "42", "source_reference": "zendesk-ticket-9001" }, "properties": { "feedback_group_id": { "description": "Target feedback group id", "title": "Feedback Group Id", "type": "string" }, "source_id": { "description": "Target source id within the group", "title": "Source Id", "type": "string" }, "field": { "$ref": "#/components/schemas/FieldContentPush" }, "source_reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Free-form identifier attached to the push for downstream tracking.", "title": "Source Reference" } }, "required": [ "feedback_group_id", "source_id", "field" ], "title": "FeedbackPushRequest", "type": "object" }, "FeedbackPushResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "feedback_group_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Feedback group the resolved source belongs to", "title": "Feedback Group Id" }, "source_id": { "description": "Resolved source id where feedback landed", "title": "Source Id", "type": "integer" }, "field_id": { "description": "Resolved field id where feedback landed", "title": "Field Id", "type": "integer" }, "inserted": { "minimum": 0, "title": "Inserted", "type": "integer" }, "rows_accepted": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "description": "Rows admitted for processing (inserted + skipped duplicates)", "title": "Rows Accepted" }, "aps_deducted": { "description": "Legacy alias of rows_accepted. Under token-based billing no APS is pre-deducted at push time \u2014 actual credit usage is metered during analysis, and test-environment keys are never charged. A fully-deduplicated retry still reports its admitted row count here.", "minimum": 0, "title": "Aps Deducted", "type": "integer" }, "skipped_duplicates": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "default": null, "title": "Skipped Duplicates" }, "duplicate_external_ids": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Duplicate External Ids" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" } }, "required": [ "status", "source_id", "field_id", "inserted", "aps_deducted" ], "title": "FeedbackPushResponse", "type": "object" }, "BulkQuestionContentPush": { "properties": { "question_id": { "description": "Target question id", "title": "Question Id", "type": "string" }, "content": { "description": "Feedback entries \u2014 bare strings or structured items", "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentItem" } ] }, "minItems": 1, "title": "Content", "type": "array" } }, "required": [ "question_id", "content" ], "title": "BulkQuestionContentPush", "type": "object" }, "BulkContentPushRequest": { "example": { "questions": [ { "content": [ "Customer feedback line 1", "Customer feedback line 2" ], "question_id": "100" }, { "content": [ "Another verbatim from a different question" ], "question_id": "101" } ], "source_reference": "zendesk-ticket-9001", "survey_id": "42", "survey_series_id": "7" }, "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "string" }, "survey_id": { "title": "Survey Id", "type": "string" }, "questions": { "description": "Up to 100 question-content pairs in a single batch", "items": { "$ref": "#/components/schemas/BulkQuestionContentPush" }, "maxItems": 100, "minItems": 1, "title": "Questions", "type": "array" }, "source_reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Reference" } }, "required": [ "survey_series_id", "survey_id", "questions" ], "title": "BulkContentPushRequest", "type": "object" }, "BulkPushAccepted": { "description": "202 body of POST /api/input/content/push/bulk.", "example": { "status": "accepted", "status_url": "/api/input/content/push/bulk/status/bp_abc123", "survey_id": 42, "survey_series_id": 7, "task_id": "bp_abc123" }, "properties": { "status": { "const": "accepted", "title": "Status", "type": "string" }, "task_id": { "title": "Task Id", "type": "string" }, "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "status_url": { "title": "Status Url", "type": "string" } }, "required": [ "status", "task_id", "survey_series_id", "survey_id", "status_url" ], "title": "BulkPushAccepted", "type": "object" }, "BulkFieldContentPush": { "properties": { "field_id": { "title": "Field Id", "type": "string" }, "content": { "items": { "anyOf": [ { "type": "string" }, { "$ref": "#/components/schemas/ContentItem" } ] }, "minItems": 1, "title": "Content", "type": "array" } }, "required": [ "field_id", "content" ], "title": "BulkFieldContentPush", "type": "object" }, "BulkFeedbackPushRequest": { "properties": { "feedback_group_id": { "title": "Feedback Group Id", "type": "string" }, "source_id": { "title": "Source Id", "type": "string" }, "fields": { "items": { "$ref": "#/components/schemas/BulkFieldContentPush" }, "maxItems": 100, "minItems": 1, "title": "Fields", "type": "array" }, "source_reference": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Reference" } }, "required": [ "feedback_group_id", "source_id", "fields" ], "title": "BulkFeedbackPushRequest", "type": "object" }, "BulkFeedbackPushAccepted": { "properties": { "status": { "const": "accepted", "title": "Status", "type": "string" }, "task_id": { "title": "Task Id", "type": "string" }, "feedback_group_id": { "title": "Feedback Group Id", "type": "integer" }, "source_id": { "title": "Source Id", "type": "integer" }, "status_url": { "title": "Status Url", "type": "string" } }, "required": [ "status", "task_id", "feedback_group_id", "source_id", "status_url" ], "title": "BulkFeedbackPushAccepted", "type": "object" }, "BulkPushStatus": { "description": "200/202 body of GET /api/input/content/push/bulk/status/{task_id}.", "example": { "completed_at": null, "created_at": "2026-06-08T10:15:00Z", "error": null, "progress": 60, "progress_message": "Inserting batch 3/5", "result": null, "status": "processing", "survey_id": 42, "survey_series_id": 7, "task_id": "bp_abc123" }, "properties": { "task_id": { "title": "Task Id", "type": "string" }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "title": "Status", "type": "string" }, "survey_series_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Survey Series Id" }, "survey_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Survey Id" }, "progress": { "default": 0, "description": "Percent complete (0-100)", "maximum": 100, "minimum": 0, "title": "Progress", "type": "number" }, "progress_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Progress Message" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 UTC", "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 UTC", "title": "Completed At" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Present on status=completed: {status, survey_series_id, survey_id, total_inserted, total_rows_accepted, total_aps_deducted, questions: [{question_id, inserted, status}, ...]}", "title": "Result" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Error payload, present on status=failed", "title": "Error" } }, "required": [ "task_id", "status" ], "title": "BulkPushStatus", "type": "object" }, "BulkFeedbackPushStatus": { "properties": { "task_id": { "title": "Task Id", "type": "string" }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "title": "Status", "type": "string" }, "feedback_group_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Feedback Group Id" }, "source_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Source Id" }, "progress": { "default": 0, "description": "Percent complete (0-100)", "maximum": 100, "minimum": 0, "title": "Progress", "type": "number" }, "progress_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Progress Message" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "completed_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Completed At" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Present on status=completed: {status, feedback_group_id, source_id, total_inserted, total_rows_accepted, total_aps_deducted, fields: [{field_id, inserted, status}, ...]}", "title": "Result" }, "error": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "title": "Error" } }, "required": [ "task_id", "status" ], "title": "BulkFeedbackPushStatus", "type": "object" }, "CreateSurveySeriesRequest": { "properties": { "name": { "description": "Series display name", "maxLength": 255, "minLength": 2, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "CreateSurveySeriesRequest", "type": "object" }, "CreatedSeriesMinimal": { "properties": { "id": { "title": "Id", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name" ], "title": "CreatedSeriesMinimal", "type": "object" }, "CreateSurveySeriesResponse": { "description": "200 (already exists) / 201 (created) body.", "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "created": { "description": "False when the series already existed", "title": "Created", "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "survey_series": { "$ref": "#/components/schemas/CreatedSeriesMinimal" } }, "required": [ "status", "created", "survey_series" ], "title": "CreateSurveySeriesResponse", "type": "object" }, "CreateFeedbackGroupRequest": { "properties": { "name": { "description": "Feedback group display name", "maxLength": 255, "minLength": 2, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "CreateFeedbackGroupRequest", "type": "object" }, "CreatedFeedbackGroupMinimal": { "properties": { "id": { "title": "Id", "type": "integer" }, "name": { "title": "Name", "type": "string" } }, "required": [ "id", "name" ], "title": "CreatedFeedbackGroupMinimal", "type": "object" }, "CreateFeedbackGroupResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "created": { "description": "False when the group already existed", "title": "Created", "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" }, "feedback_group": { "$ref": "#/components/schemas/CreatedFeedbackGroupMinimal" } }, "required": [ "status", "created", "feedback_group" ], "title": "CreateFeedbackGroupResponse", "type": "object" }, "CreateSurveyQuestion": { "description": "One question in the create-survey payload. Permissive on\nquestion_type to match the existing case-insensitive parser.", "properties": { "question_title": { "maxLength": 500, "minLength": 1, "title": "Question Title", "type": "string" }, "question_type": { "description": "One of DEPTH_TEXT, TEXT, MCQ, SCQ, RATING, NPS, METADATA (case-insensitive; also accepts long_answer / short_answer).", "title": "Question Type", "type": "string" }, "question_options": { "items": { "type": "string" }, "maxItems": 100, "title": "Question Options", "type": "array" }, "is_mandatory": { "default": false, "title": "Is Mandatory", "type": "boolean" }, "min_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Min Value" }, "max_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Value" }, "min_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Min Label" }, "max_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Max Label" }, "use_star_rating": { "default": false, "title": "Use Star Rating", "type": "boolean" } }, "required": [ "question_title", "question_type" ], "title": "CreateSurveyQuestion", "type": "object" }, "CreateSurveyRequest": { "properties": { "survey_series_id": { "title": "Survey Series Id", "type": "string" }, "survey_title": { "maxLength": 100, "minLength": 1, "title": "Survey Title", "type": "string" }, "survey_description": { "default": "", "maxLength": 1000, "title": "Survey Description", "type": "string" }, "feedback_type": { "default": "survey", "description": "What kind of feedback this source collects: survey | call_transcript | app_review | support_ticket | chat | email | social_media | review | other. Open vocabulary \u2014 new types may be added without a version bump.", "title": "Feedback Type", "type": "string" }, "questions": { "items": { "$ref": "#/components/schemas/CreateSurveyQuestion" }, "title": "Questions", "type": "array" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "EN | FR | ES (or full names; case-insensitive)", "title": "Language" } }, "required": [ "survey_series_id", "survey_title" ], "title": "CreateSurveyRequest", "type": "object" }, "CreatedQuestion": { "properties": { "id": { "title": "Id", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "description": "The normalized question type echoed back", "title": "Type", "type": "string" } }, "required": [ "id", "title", "type" ], "title": "CreatedQuestion", "type": "object" }, "CreateSurveyResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "feedback_type": { "default": "survey", "title": "Feedback Type", "type": "string" }, "questions_created": { "title": "Questions Created", "type": "integer" }, "questions": { "items": { "$ref": "#/components/schemas/CreatedQuestion" }, "title": "Questions", "type": "array" }, "message": { "title": "Message", "type": "string" } }, "required": [ "status", "survey_series_id", "survey_id", "questions_created", "questions", "message" ], "title": "CreateSurveyResponse", "type": "object" }, "CreateSourceField": { "properties": { "field_title": { "maxLength": 500, "minLength": 1, "title": "Field Title", "type": "string" }, "field_type": { "description": "One of DEPTH_TEXT, TEXT, MCQ, SCQ, RATING, NPS, METADATA (case-insensitive; also accepts long_answer / short_answer).", "title": "Field Type", "type": "string" }, "field_options": { "items": { "type": "string" }, "maxItems": 100, "title": "Field Options", "type": "array" }, "is_mandatory": { "default": false, "title": "Is Mandatory", "type": "boolean" }, "min_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Min Value" }, "max_value": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max Value" }, "min_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Min Label" }, "max_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Max Label" }, "use_star_rating": { "default": false, "title": "Use Star Rating", "type": "boolean" } }, "required": [ "field_title", "field_type" ], "title": "CreateSourceField", "type": "object" }, "CreateSourceRequest": { "properties": { "feedback_group_id": { "title": "Feedback Group Id", "type": "string" }, "source_title": { "maxLength": 100, "minLength": 1, "title": "Source Title", "type": "string" }, "source_description": { "default": "", "maxLength": 1000, "title": "Source Description", "type": "string" }, "feedback_type": { "default": "survey", "description": "What kind of feedback this source collects: survey | call_transcript | app_review | support_ticket | chat | email | social_media | review | other. Open vocabulary.", "title": "Feedback Type", "type": "string" }, "fields": { "items": { "$ref": "#/components/schemas/CreateSourceField" }, "maxItems": 100, "title": "Fields", "type": "array" }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "EN | FR | ES (case-insensitive)", "title": "Language" } }, "required": [ "feedback_group_id", "source_title" ], "title": "CreateSourceRequest", "type": "object" }, "CreatedField": { "properties": { "id": { "title": "Id", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" } }, "required": [ "id", "title", "type" ], "title": "CreatedField", "type": "object" }, "CreateSourceResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "feedback_group_id": { "title": "Feedback Group Id", "type": "integer" }, "source_id": { "title": "Source Id", "type": "integer" }, "feedback_type": { "default": "survey", "title": "Feedback Type", "type": "string" }, "fields_created": { "title": "Fields Created", "type": "integer" }, "fields": { "items": { "$ref": "#/components/schemas/CreatedField" }, "title": "Fields", "type": "array" }, "message": { "title": "Message", "type": "string" } }, "required": [ "status", "feedback_group_id", "source_id", "fields_created", "fields", "message" ], "title": "CreateSourceResponse", "type": "object" }, "PublishSurveyRequest": { "properties": { "survey_id": { "title": "Survey Id", "type": "integer" }, "survey_series_id": { "title": "Survey Series Id", "type": "integer" } }, "required": [ "survey_id", "survey_series_id" ], "title": "PublishSurveyRequest", "type": "object" }, "PublishSurveyResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "survey_id": { "title": "Survey Id", "type": "integer" }, "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "mode": { "const": "ACCESSIBLE", "title": "Mode", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "status", "survey_id", "survey_series_id", "mode", "message" ], "title": "PublishSurveyResponse", "type": "object" }, "PublishSourceRequest": { "properties": { "source_id": { "title": "Source Id", "type": "integer" }, "feedback_group_id": { "title": "Feedback Group Id", "type": "integer" } }, "required": [ "source_id", "feedback_group_id" ], "title": "PublishSourceRequest", "type": "object" }, "PublishSourceResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "source_id": { "title": "Source Id", "type": "integer" }, "feedback_group_id": { "title": "Feedback Group Id", "type": "integer" }, "mode": { "const": "ACCESSIBLE", "title": "Mode", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "status", "source_id", "feedback_group_id", "mode", "message" ], "title": "PublishSourceResponse", "type": "object" }, "ListPagination": { "description": "Series-level pagination echo on the surveys-list endpoints.\n\n``total_count`` is the number of series matching the filters, so\nclients page while ``offset + limit < total_count``.", "properties": { "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "total_count": { "title": "Total Count", "type": "integer" } }, "required": [ "limit", "offset", "total_count" ], "title": "ListPagination", "type": "object" }, "QuestionListing": { "properties": { "id": { "title": "Id", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" }, "options": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Options" }, "accepts_content": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Accepts Content" }, "content_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "One of text | numeric | single_choice | multi_choice", "title": "Content Format" }, "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Min" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max" } }, "required": [ "id", "title", "type" ], "title": "QuestionListing", "type": "object" }, "SeriesListing": { "properties": { "id": { "title": "Id", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "surveys": { "items": { "$ref": "#/components/schemas/SurveyListing" }, "title": "Surveys", "type": "array" } }, "required": [ "id", "name" ], "title": "SeriesListing", "type": "object" }, "SurveyListing": { "properties": { "id": { "title": "Id", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mode" }, "feedback_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What kind of feedback this source collects (survey | call_transcript | \u2026)", "title": "Feedback Type" }, "questions": { "items": { "$ref": "#/components/schemas/QuestionListing" }, "title": "Questions", "type": "array" } }, "required": [ "id", "title" ], "title": "SurveyListing", "type": "object" }, "SurveysListResponse": { "description": "Body of GET /api/input/surveys and /api/input/surveys/list.\n\nThe `org_id` field is present on the API-key endpoint and omitted on\nthe Clerk endpoint \u2014 declare it Optional.", "example": { "org_id": 31, "survey_series": [ { "id": 7, "name": "Customer Support", "surveys": [ { "description": "Monthly post-ticket survey", "id": 42, "mode": "ACCESSIBLE", "questions": [ { "accepts_content": true, "content_format": "text", "id": 100, "title": "What could we improve?", "type": "long_answer" } ], "title": "CSAT \u2014 March 2026" } ] } ] }, "properties": { "survey_series": { "items": { "$ref": "#/components/schemas/SeriesListing" }, "title": "Survey Series", "type": "array" }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/ListPagination" }, { "type": "null" } ], "default": null }, "org_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Org Id" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" } }, "title": "SurveysListResponse", "type": "object" }, "FeedbackGroupListing": { "properties": { "id": { "title": "Id", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "sources": { "items": { "$ref": "#/components/schemas/SourceListing" }, "title": "Sources", "type": "array" } }, "required": [ "id", "name" ], "title": "FeedbackGroupListing", "type": "object" }, "FieldListing": { "properties": { "id": { "title": "Id", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "type": { "title": "Type", "type": "string" }, "options": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "default": null, "title": "Options" }, "accepts_content": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Accepts Content" }, "content_format": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "One of text | numeric | single_choice | multi_choice", "title": "Content Format" }, "min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Min" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Max" } }, "required": [ "id", "title", "type" ], "title": "FieldListing", "type": "object" }, "SourceListing": { "properties": { "id": { "title": "Id", "type": "integer" }, "title": { "title": "Title", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" }, "mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Mode" }, "feedback_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "What kind of feedback this source collects (survey | call_transcript | \u2026)", "title": "Feedback Type" }, "fields": { "items": { "$ref": "#/components/schemas/FieldListing" }, "title": "Fields", "type": "array" } }, "required": [ "id", "title" ], "title": "SourceListing", "type": "object" }, "SourcesListResponse": { "description": "Body of GET /api/input/sources/list (partner-vocabulary variant).", "properties": { "feedback_groups": { "items": { "$ref": "#/components/schemas/FeedbackGroupListing" }, "title": "Feedback Groups", "type": "array" }, "pagination": { "anyOf": [ { "$ref": "#/components/schemas/ListPagination" }, { "type": "null" } ], "default": null }, "org_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Org Id" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" } }, "title": "SourcesListResponse", "type": "object" }, "AnalysisFlag": { "properties": { "name": { "title": "Name", "type": "string" }, "mentions": { "minimum": 0, "title": "Mentions", "type": "integer" }, "avg_sentiment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Avg Sentiment" }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Summary" }, "scope": { "const": "survey_series", "default": "survey_series", "description": "Flags are monitored at feedback-group level; the list covers the whole group this survey belongs to.", "title": "Scope", "type": "string" } }, "required": [ "name", "mentions" ], "title": "AnalysisFlag", "type": "object" }, "AnalysisTheme": { "properties": { "name": { "title": "Name", "type": "string" }, "mentions": { "minimum": 0, "title": "Mentions", "type": "integer" }, "avg_sentiment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "-1..1 average sentiment across mentions", "title": "Avg Sentiment" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Description" } }, "required": [ "name", "mentions" ], "title": "AnalysisTheme", "type": "object" }, "SentimentDistribution": { "description": "5-tier mention-weighted sentiment distribution.", "properties": { "veryPositive": { "default": 0, "title": "Verypositive", "type": "integer" }, "positive": { "default": 0, "title": "Positive", "type": "integer" }, "neutral": { "default": 0, "title": "Neutral", "type": "integer" }, "negative": { "default": 0, "title": "Negative", "type": "integer" }, "veryNegative": { "default": 0, "title": "Verynegative", "type": "integer" } }, "title": "SentimentDistribution", "type": "object" }, "SurveyAnalysisReadResponse": { "description": "Processed analysis for one survey \u2014 the read half of the API.\n\n``analysis_status`` is 'available' once at least one analysis run has\nsettled; 'none' means no analysis exists yet (nothing pushed, or the\nfirst run is still in flight \u2014 subscribe to the `analysis.completed`\nwebhook instead of polling).\n\n``analysis_id`` names the source's all-time analysis run. A source whose\nfeedback group tracks trends over time is analyzed per period instead:\nit has no single run to name, so ``analysis_id`` is null while\n``analysis_status`` is 'available' and the figures aggregate every\nanalyzed period.", "properties": { "survey_id": { "title": "Survey Id", "type": "integer" }, "survey_series_id": { "title": "Survey Series Id", "type": "integer" }, "feedback_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Feedback Type" }, "analysis_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Analysis Id" }, "analysis_status": { "enum": [ "available", "none" ], "title": "Analysis Status", "type": "string" }, "sentiment_distribution": { "$ref": "#/components/schemas/SentimentDistribution" }, "themes": { "items": { "$ref": "#/components/schemas/AnalysisTheme" }, "title": "Themes", "type": "array" }, "flags": { "items": { "$ref": "#/components/schemas/AnalysisFlag" }, "title": "Flags", "type": "array" } }, "required": [ "survey_id", "survey_series_id", "analysis_status", "sentiment_distribution" ], "title": "SurveyAnalysisReadResponse", "type": "object" }, "SourceAnalysisReadResponse": { "description": "Partner-vocabulary variant of SurveyAnalysisReadResponse.", "properties": { "source_id": { "title": "Source Id", "type": "integer" }, "feedback_group_id": { "title": "Feedback Group Id", "type": "integer" }, "feedback_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Feedback Type" }, "analysis_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Analysis Id" }, "analysis_status": { "enum": [ "available", "none" ], "title": "Analysis Status", "type": "string" }, "sentiment_distribution": { "$ref": "#/components/schemas/SentimentDistribution" }, "themes": { "items": { "$ref": "#/components/schemas/AnalysisTheme" }, "title": "Themes", "type": "array" }, "flags": { "items": { "$ref": "#/components/schemas/AnalysisFlag" }, "title": "Flags", "type": "array" } }, "required": [ "source_id", "feedback_group_id", "analysis_status", "sentiment_distribution" ], "title": "SourceAnalysisReadResponse", "type": "object" }, "KeyCreditsStatus": { "additionalProperties": true, "description": "APS credit status of the calling key's org, as returned by\n``GET /api/input/me``. Extra keys may be added over time.", "properties": { "plan_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Deprecated \u2014 plans no longer exist; always absent", "title": "Plan Key" }, "limit": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "APS quota for the current billing period", "title": "Limit" }, "used": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "APS consumed this period (fractional under token billing)", "title": "Used" }, "remaining": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "description": "APS remaining this period", "title": "Remaining" }, "period_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 period start, null on the free plan", "title": "Period Start" }, "period_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 period end, null on the free plan", "title": "Period End" }, "rate_tokens_per_aps": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "description": "Live token-to-APS conversion rate", "title": "Rate Tokens Per Aps" } }, "title": "KeyCreditsStatus", "type": "object" }, "KeyRateLimits": { "properties": { "per_key_per_minute": { "title": "Per Key Per Minute", "type": "integer" }, "per_org_per_minute": { "title": "Per Org Per Minute", "type": "integer" }, "per_ip_per_minute": { "title": "Per Ip Per Minute", "type": "integer" }, "window_seconds": { "title": "Window Seconds", "type": "integer" } }, "required": [ "per_key_per_minute", "per_org_per_minute", "per_ip_per_minute", "window_seconds" ], "title": "KeyRateLimits", "type": "object" }, "KeySelfInfoResponse": { "description": "GET /api/input/me \u2014 what the calling key can see about itself.", "properties": { "key": { "additionalProperties": true, "description": "Public key fields (id, name, environment, permissions, \u2026)", "title": "Key", "type": "object" }, "org_id": { "title": "Org Id", "type": "integer" }, "rate_limits": { "$ref": "#/components/schemas/KeyRateLimits" }, "credits": { "anyOf": [ { "$ref": "#/components/schemas/KeyCreditsStatus" }, { "type": "null" } ], "default": null, "description": "APS credit status for the key's org" }, "webhook_events": { "description": "Event types available for webhook subscriptions", "items": { "type": "string" }, "title": "Webhook Events", "type": "array" } }, "required": [ "key", "org_id", "rate_limits" ], "title": "KeySelfInfoResponse", "type": "object" }, "FeedbackItem": { "properties": { "id": { "description": "Cursor-orderable item id", "title": "Id", "type": "integer" }, "source_id": { "title": "Source Id", "type": "integer" }, "field_id": { "title": "Field Id", "type": "integer" }, "type": { "description": "text | numeric | choice", "title": "Type", "type": "string" }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Text" }, "numeric": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "default": null, "title": "Numeric" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Id" }, "metadata": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "default": null, "description": "Structured ingest metadata as pushed", "title": "Metadata" }, "source_reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Source Reference" }, "occurred_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ISO-8601 event time", "title": "Occurred At" } }, "required": [ "id", "source_id", "field_id", "type" ], "title": "FeedbackItem", "type": "object" }, "FeedbackListResponse": { "description": "Cursor page of API-pushed feedback (partner vocabulary).", "properties": { "items": { "items": { "$ref": "#/components/schemas/FeedbackItem" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Pass back as ?cursor= to fetch the next page; null on the last page", "title": "Next Cursor" }, "has_more": { "default": false, "title": "Has More", "type": "boolean" } }, "title": "FeedbackListResponse", "type": "object" }, "EraseFeedbackRequest": { "description": "Selector for a bulk erasure. Exactly one of external_ids /\ncustomer_id is required; feedback_group_id optionally narrows scope.", "properties": { "external_ids": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 1000, "type": "array" }, { "type": "null" } ], "default": null, "title": "External Ids" }, "customer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Erase every item whose ingest metadata carries this customer_id", "title": "Customer Id" }, "feedback_group_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Feedback Group Id" } }, "title": "EraseFeedbackRequest", "type": "object" }, "EraseFeedbackResponse": { "properties": { "status": { "const": "success", "title": "Status", "type": "string" }, "deleted": { "description": "Answer rows deleted", "minimum": 0, "title": "Deleted", "type": "integer" }, "sources_affected": { "minimum": 0, "title": "Sources Affected", "type": "integer" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Message" } }, "required": [ "status", "deleted", "sources_affected" ], "title": "EraseFeedbackResponse", "type": "object" }, "InviteTemplateInfo": { "description": "GET /api/input/sources/{id}/invite-template \u2014 what an integration\nneeds to know before calling the send endpoint.", "properties": { "configured": { "title": "Configured", "type": "boolean" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "variables": { "description": "Column keys available as {{tokens}} in the template", "items": { "type": "string" }, "title": "Variables", "type": "array" }, "sender_domain_verified": { "default": false, "title": "Sender Domain Verified", "type": "boolean" }, "sending_enabled": { "description": "True when template + verified domain + published survey are all in place", "title": "Sending Enabled", "type": "boolean" }, "daily_quota": { "default": 0, "title": "Daily Quota", "type": "integer" }, "daily_quota_used": { "default": 0, "title": "Daily Quota Used", "type": "integer" } }, "required": [ "configured", "sending_enabled" ], "title": "InviteTemplateInfo", "type": "object" }, "InviteRecipient": { "example": { "email": "marie@example.com", "external_id": "ticket-4521", "variables": { "agent": "Lucas", "first_name": "Marie" } }, "properties": { "email": { "maxLength": 320, "title": "Email", "type": "string" }, "external_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "default": null, "description": "Your correlation id for this contact \u2014 echoed on the recipients listing.", "title": "External Id" }, "variables": { "additionalProperties": true, "description": "Values for the template's {{column_key}} tokens. Keys must match the respondent list's columns configured in the platform; unknown keys are rejected with the available column list.", "title": "Variables", "type": "object" } }, "required": [ "email" ], "title": "InviteRecipient", "type": "object" }, "SendInvitesRequest": { "properties": { "recipients": { "items": { "$ref": "#/components/schemas/InviteRecipient" }, "maxItems": 1000, "minItems": 1, "title": "Recipients", "type": "array" }, "resend": { "default": false, "description": "Re-invite addresses that already received this survey (default: they are skipped).", "title": "Resend", "type": "boolean" }, "dry_run": { "default": false, "description": "Render previews for the first recipients and send nothing.", "title": "Dry Run", "type": "boolean" } }, "required": [ "recipients" ], "title": "SendInvitesRequest", "type": "object" }, "InvitePreview": { "properties": { "email": { "title": "Email", "type": "string" }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Subject" }, "body_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Body Html" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" } }, "required": [ "email" ], "title": "InvitePreview", "type": "object" }, "SendInvitesDryRun": { "description": "200 body of a dry_run call \u2014 nothing was sent or persisted.", "properties": { "status": { "const": "dry_run", "title": "Status", "type": "string" }, "previews": { "items": { "$ref": "#/components/schemas/InvitePreview" }, "title": "Previews", "type": "array" }, "would_accept": { "minimum": 0, "title": "Would Accept", "type": "integer" }, "skipped_already_invited": { "items": { "type": "string" }, "title": "Skipped Already Invited", "type": "array" }, "invalid": { "items": { "type": "string" }, "title": "Invalid", "type": "array" } }, "required": [ "status", "would_accept" ], "title": "SendInvitesDryRun", "type": "object" }, "SendInvitesAccepted": { "description": "202 body \u2014 the distribution was queued.", "properties": { "status": { "const": "accepted", "title": "Status", "type": "string" }, "distribution_id": { "title": "Distribution Id", "type": "integer" }, "task_id": { "title": "Task Id", "type": "string" }, "accepted": { "description": "Recipients queued for sending", "minimum": 0, "title": "Accepted", "type": "integer" }, "skipped_already_invited": { "items": { "type": "string" }, "title": "Skipped Already Invited", "type": "array" }, "invalid": { "items": { "type": "string" }, "title": "Invalid", "type": "array" }, "status_url": { "title": "Status Url", "type": "string" } }, "required": [ "status", "distribution_id", "task_id", "accepted", "status_url" ], "title": "SendInvitesAccepted", "type": "object" }, "InviteDistributionStatus": { "description": "GET /api/input/invites/{distribution_id}.", "properties": { "distribution_id": { "title": "Distribution Id", "type": "integer" }, "survey_id": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Survey Id" }, "status": { "enum": [ "pending", "sending", "sent", "partial", "failed", "canceled" ], "title": "Status", "type": "string" }, "total": { "default": 0, "title": "Total", "type": "integer" }, "sent": { "default": 0, "title": "Sent", "type": "integer" }, "failed": { "default": 0, "title": "Failed", "type": "integer" }, "skipped": { "default": 0, "title": "Skipped", "type": "integer" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "finished_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Finished At" } }, "required": [ "distribution_id", "status" ], "title": "InviteDistributionStatus", "type": "object" }, "InviteRecipientStatus": { "properties": { "id": { "description": "Cursor-orderable row id", "title": "Id", "type": "integer" }, "email": { "title": "Email", "type": "string" }, "external_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "External Id" }, "status": { "enum": [ "pending", "sent", "failed", "skipped" ], "title": "Status", "type": "string" }, "delivery_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "ESP outcome: delivered | bounced | dropped | complained. Null until an event arrives.", "title": "Delivery Status" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Error" } }, "required": [ "id", "email", "status" ], "title": "InviteRecipientStatus", "type": "object" }, "InviteRecipientsPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/InviteRecipientStatus" }, "title": "Items", "type": "array" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Next Cursor" }, "has_more": { "default": false, "title": "Has More", "type": "boolean" } }, "title": "InviteRecipientsPage", "type": "object" }, "WebhookDict": { "additionalProperties": true, "description": "Public representation of a configured webhook subscription.", "properties": { "id": { "title": "Id", "type": "integer" }, "org_id": { "title": "Org Id", "type": "integer" }, "name": { "title": "Name", "type": "string" }, "url": { "title": "Url", "type": "string" }, "events": { "items": { "type": "string" }, "title": "Events", "type": "array" }, "is_active": { "title": "Is Active", "type": "boolean" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Created At" }, "last_delivery_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Last Delivery At" } }, "required": [ "id", "org_id", "name", "url", "events", "is_active" ], "title": "WebhookDict", "type": "object" }, "CreateWebhookRequest": { "properties": { "name": { "maxLength": 255, "minLength": 1, "title": "Name", "type": "string" }, "url": { "description": "HTTPS endpoint to POST events to", "title": "Url", "type": "string" }, "events": { "description": "One or more event types: content.pushed, survey.created, survey.published, series.created, analysis.completed, flag.raised, report.ready, invites.completed, invite.bounced", "items": { "type": "string" }, "minItems": 1, "title": "Events", "type": "array" } }, "required": [ "name", "url", "events" ], "title": "CreateWebhookRequest", "type": "object" }, "CreateWebhookResponse": { "properties": { "webhook": { "$ref": "#/components/schemas/WebhookDict" }, "secret": { "description": "HMAC secret shown once. Returned again only via regenerate-secret.", "title": "Secret", "type": "string" }, "message": { "title": "Message", "type": "string" } }, "required": [ "webhook", "secret", "message" ], "title": "CreateWebhookResponse", "type": "object" } }, "securitySchemes": { "apiKeyAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "BAI Analytics API key", "description": "API key authentication: pass your key in the Authorization header as `Bearer inpk_live_...` (or `inpk_test_...` for a test-environment key). Create and manage keys in the dashboard under Integrations Hub -> API Keys. Each key carries a permission scope (push, create, send, mcp_read, or all) and a per-minute rate limit." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Opaque client-supplied key for safe POST retries. Repeated requests with the same key within a 24-hour window replay the original response instead of executing the mutation twice. Reusing the same key with a DIFFERENT request body returns 409 `IDEMPOTENCY_ERROR`. Backed by ``input_api_idempotency_keys`` in Postgres.", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "examples": [ "evt_2025_05_19_a1b2c3" ] } } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying. Emitted on 429 responses and on 503 responses from the global rate limiter. Rate-limit windows are fixed (anchored at the first request in the window): requests rejected with 429 do not extend the window, so waiting until ``X-RateLimit-Reset`` always recovers.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitLimit": { "description": "Total requests allowed in the current rate-limit window.", "schema": { "type": "integer", "minimum": 1 } }, "XRateLimitRemaining": { "description": "Requests remaining in the current rate-limit window.", "schema": { "type": "integer", "minimum": 0 } }, "XRateLimitReset": { "description": "Unix timestamp when the rate-limit window resets. The window is fixed from its first request \u2014 429-rejected requests do not push this forward.", "schema": { "type": "integer", "minimum": 0 } } }, "responses": { "RateLimited": { "description": "Rate limit exceeded \u2014 see Retry-After header.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/XRateLimitLimit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/XRateLimitRemaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/XRateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "webhooks": { "content.pushed": { "post": { "summary": "Receive a content.pushed event", "description": "BAI Analytics POSTs to your subscribed URL when the `content.pushed` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPushedEvent" }, "example": { "event": "content.pushed", "timestamp": "2026-07-12T09:30:05Z", "data": { "survey_series_id": 1842, "survey_id": 9021, "question_id": 31245, "original_survey_id": 9021, "original_question_id": 31245, "lines_pushed": 2, "api_key_id": 77 } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "series.created": { "post": { "summary": "Receive a series.created event", "description": "BAI Analytics POSTs to your subscribed URL when the `series.created` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeriesCreatedEvent" }, "example": { "event": "series.created", "timestamp": "2026-07-12T09:00:00Z", "data": { "survey_series_id": 1842, "name": "Customer Support EU", "api_key_id": 77 } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "survey.created": { "post": { "summary": "Receive a survey.created event", "description": "BAI Analytics POSTs to your subscribed URL when the `survey.created` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyCreatedEvent" }, "example": { "event": "survey.created", "timestamp": "2026-07-12T09:01:00Z", "data": { "survey_series_id": 1842, "survey_id": 9021, "survey_title": "Support tickets (CRM sync)", "questions_created": 2, "api_key_id": 77 } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "survey.published": { "post": { "summary": "Receive a survey.published event", "description": "BAI Analytics POSTs to your subscribed URL when the `survey.published` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyPublishedEvent" }, "example": { "event": "survey.published", "timestamp": "2026-07-12T09:02:00Z", "data": { "survey_series_id": 1842, "survey_id": 9021, "survey_name": "Support tickets (CRM sync)", "api_key_id": 77 } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "analysis.completed": { "post": { "summary": "Receive a analysis.completed event", "description": "BAI Analytics POSTs to your subscribed URL when the `analysis.completed` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalysisCompletedEvent" }, "example": { "event": "analysis.completed", "timestamp": "2026-07-12T09:45:12Z", "data": { "survey_series_id": 1842, "survey_id": 9021, "analysis_id": 55710, "survey_name": "Support tickets (CRM sync)" } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "flag.raised": { "post": { "summary": "Receive a flag.raised event", "description": "BAI Analytics POSTs to your subscribed URL when the `flag.raised` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagRaisedEvent" }, "example": { "event": "flag.raised", "timestamp": "2026-07-12T09:46:00Z", "data": { "survey_series_id": 1842, "survey_id": 9021, "analysis_id": 55710, "survey_name": "Support tickets (CRM sync)", "group_name": "Customer Support EU", "trigger_type": "scan_complete", "flag_counts": { "Churn risk": 3 }, "total_flagged": 17 } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "report.ready": { "post": { "summary": "Receive a report.ready event", "description": "BAI Analytics POSTs to your subscribed URL when the `report.ready` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportReadyEvent" }, "example": { "event": "report.ready", "timestamp": "2026-08-01T06:00:00Z", "data": { "survey_series_id": 1842, "subscription_id": 12, "period_key": "2026-07", "report_id": 3311, "report_name": "Customer Support EU - July 2026" } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "invites.completed": { "post": { "summary": "Receive a invites.completed event", "description": "BAI Analytics POSTs to your subscribed URL when the `invites.completed` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitesCompletedEvent" }, "example": { "event": "invites.completed", "timestamp": "2026-07-12T10:06:31Z", "data": { "distribution_id": 7301, "survey_id": 9021, "status": "completed", "total": 1000, "sent": 991, "failed": 4, "skipped": 5 } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } }, "invite.bounced": { "post": { "summary": "Receive a invite.bounced event", "description": "BAI Analytics POSTs to your subscribed URL when the `invite.bounced` event fires. The raw body is signed with the subscription's HMAC secret via the `X-Boundary-Signature: sha256=` header, and `X-Boundary-Event` carries the event type. Respond 2xx within 30s or the delivery is retried up to 3 times (after 1, 5, then 15 minutes).", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteBouncedEvent" }, "example": { "event": "invite.bounced", "timestamp": "2026-07-12T10:07:02Z", "data": { "distribution_id": 7301, "survey_id": 9021, "email": "bounced@example.com", "reason": "bounce" } } } } }, "responses": { "200": { "description": "Acknowledged \u2014 no retry" }, "204": { "description": "Acknowledged \u2014 no retry" }, "4XX": { "description": "Receiver rejected the delivery \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "5XX": { "description": "Receiver errored \u2014 BAI Analytics retries after 1, 5, then 15 minutes." }, "default": { "description": "Any non-2xx triggers retry, up to 3 attempts (after 1, 5, then 15 minutes)." } } } } } }