{ "openapi": "3.1.0", "info": { "title": "chatform API", "description": "Agentic chatbot forms platform. /p/* = public respondent surface, /v1/* = developer API (API key), /api/* = dashboard (session auth).", "version": "1.0.0" }, "servers": [ { "url": "https://api.chatform.in", "description": "Production" }, { "url": "http://localhost:8787", "description": "Local development" } ], "tags": [ { "name": "v1", "description": "Developer API — API key auth" }, { "name": "public", "description": "Respondent chat surface" }, { "name": "health", "description": "Service health" } ], "components": { "securitySchemes": { "secretKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_…", "description": "A server-side secret key. Never send one from a browser — a request carrying an Origin header is refused for this reason." }, "publishableKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pk_live_…", "description": "A browser-safe key, restricted to the origins listed on it." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "The same keys, in the header most integrators reach for first." }, "respondentToken": { "type": "apiKey", "in": "header", "name": "x-respondent-token", "description": "Scoped to one chat session, and it expires. This is what a browser should hold." }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "better-auth.session_token", "description": "The dashboard's own session." } }, "schemas": { "ErrorEnvelope": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ], "additionalProperties": false } } }, "paths": { "/health": { "get": { "operationId": "getHealth", "tags": [ "health" ], "summary": "Service health", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "env": { "type": "string" }, "db": { "type": "string" }, "ts": { "type": "number" } }, "required": [ "ok", "env", "db", "ts" ] } } } } } } }, "/v1/forms/{id}/responses": { "post": { "operationId": "postV1FormsByIdResponses", "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hiddenFields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_.-]{0,60}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "complete": { "default": false, "type": "boolean" }, "mode": { "default": "flow", "type": "string", "enum": [ "flow", "free" ] }, "expiresIn": { "default": 86400, "type": "integer", "minimum": 300, "maximum": 2592000 }, "respondent": { "type": "object", "properties": { "country": { "type": "string", "maxLength": 8 }, "userAgent": { "type": "string", "maxLength": 300 } } } } } } } }, "tags": [ "v1" ], "summary": "Open a response (optionally with answers, optionally completing it)", "responses": { "201": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The form is not live", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "An answer was rejected, or required questions are unanswered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] }, "get": { "operationId": "getV1FormsByIdResponses", "parameters": [ { "in": "query", "name": "status", "schema": { "type": "string" } }, { "in": "query", "name": "source", "schema": { "type": "string" } }, { "in": "query", "name": "mode", "schema": { "type": "string", "enum": [ "live", "test", "all" ] } }, { "in": "query", "name": "created_after", "schema": { "type": "number" } }, { "in": "query", "name": "created_before", "schema": { "type": "number" } }, { "in": "query", "name": "updated_since", "schema": { "type": "number" } }, { "in": "query", "name": "ending_ref", "schema": { "type": "string" } }, { "in": "query", "name": "q", "schema": { "type": "string", "maxLength": 200 } }, { "in": "query", "name": "order", "schema": { "default": "created", "type": "string", "enum": [ "created", "updated" ] } }, { "in": "query", "name": "include", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "tags": [ "v1" ], "summary": "List a form's responses, newest first", "responses": { "200": { "description": "A page of responses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "400": { "description": "Malformed cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "402": { "description": "Reading partial responses needs a plan that includes them", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "response:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/responses/{id}/answers": { "post": { "operationId": "postV1ResponsesByIdAnswers", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "answers": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "answers" ] }, { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } ] } } } }, "tags": [ "v1" ], "summary": "Record one or more answers on an open response", "parameters": [ { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated extras. `answers` adds every answer as `{ ref, type, value }`." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Updated response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } } } }, "404": { "description": "Response not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The response is no longer open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "An answer was rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "response:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/responses/{id}/answers/{ref}": { "delete": { "operationId": "deleteV1ResponsesByIdAnswersByRef", "tags": [ "v1" ], "summary": "Retract one answer, moving the flow back to it", "parameters": [ { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated extras. `answers` adds every answer as `{ ref, type, value }`." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "ref", "required": true } ], "responses": { "200": { "description": "Updated response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "response:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/responses/{id}/complete": { "post": { "operationId": "postV1ResponsesByIdComplete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endingRef": { "type": "string" } } } } } }, "tags": [ "v1" ], "summary": "Complete a response", "responses": { "200": { "description": "Completed response with its ending", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Already finished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Required questions are unanswered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/responses/{id}/abandon": { "post": { "operationId": "postV1ResponsesByIdAbandon", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 100 } } } } } }, "tags": [ "v1" ], "summary": "Abandon an unfinished response", "responses": { "200": { "description": "Abandoned response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/responses/{id}": { "get": { "operationId": "getV1ResponsesById", "tags": [ "v1" ], "summary": "Read one response", "parameters": [ { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated extras. `answers` adds every answer as `{ ref, type, value }`." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "response" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "abandoned", "disqualified" ] }, "source": { "type": "string", "enum": [ "chat", "embed", "api" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "started_at": { "type": "number" }, "updated_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "abandon_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "link", "inline", "popup", "side_tab", "fullpage", "embed", "api" ] }, "pageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referrerHost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "utm": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "screen": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "device": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "enum": [ "mobile", "tablet", "desktop", "bot" ] }, { "type": "null" } ] }, "browser": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "browserVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "os": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "osVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "type", "browser", "browserVersion", "os", "osVersion" ] }, "geo": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "regionCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "continent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "country", "region", "regionCode", "city", "postalCode", "latitude", "longitude", "continent", "timezone" ] }, "network": { "type": "object", "properties": { "asn": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "organization": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "asn", "organization" ] } }, "required": [ "channel", "pageUrl", "referrer", "referrerHost", "utm", "language", "screen", "timezone", "device", "geo", "network" ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "hidden_fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "complete_ready": { "type": "boolean" }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "off_path_answers": { "type": "array", "items": { "type": "string" } }, "answers": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "value": {} }, "required": [ "ref", "type", "value" ] } }, "recorded": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "value": {} }, "required": [ "ref", "value" ] } } }, "required": [ "id", "object", "form_id", "status", "source", "mode", "started_at", "updated_at", "completed_at", "expires_at", "duration_ms", "ending_ref", "abandon_reason", "metadata", "progress", "variables", "hidden_fields", "next", "complete_ready", "missing_required", "off_path_answers" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "response:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/responses/{id}/next": { "get": { "operationId": "getV1ResponsesByIdNext", "tags": [ "v1" ], "summary": "Where the flow is waiting on this response", "responses": { "200": { "description": "The next question, or the ending", "content": { "application/json": { "schema": { "type": "object", "properties": { "next": { "anyOf": [ { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "block" }, "block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } }, "required": [ "kind", "block" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "ending" }, "ending": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} } }, "required": [ "kind", "ending" ] } ] }, { "type": "null" } ] }, "progress": { "type": "object", "properties": { "answered": { "type": "number" }, "totalEstimate": { "type": "number" }, "pct": { "type": "number" } }, "required": [ "answered", "totalEstimate", "pct" ] }, "answered": { "type": "array", "items": {} }, "missing_required": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" } }, "required": [ "ref", "title" ] } }, "complete_ready": { "type": "boolean" } }, "required": [ "next", "progress", "answered", "missing_required", "complete_ready" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/blocks": { "get": { "operationId": "getV1Blocks", "tags": [ "v1" ], "summary": "Every block type: config schema, what you receive, what you send", "responses": { "200": { "description": "The block catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "schema_version": { "type": "number" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "summary": { "type": "string" }, "config_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "needs_options": { "type": "boolean" }, "answered_by": { "type": "string" }, "config_schema": {}, "public_block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, "answer": {} }, "required": [ "type", "summary", "config_hint", "needs_options", "answered_by", "config_schema", "public_block", "answer" ], "additionalProperties": {} } } }, "required": [ "schema_version", "blocks" ] } } } } }, "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/blocks/{type}": { "get": { "operationId": "getV1BlocksByType", "tags": [ "v1" ], "summary": "One block type", "responses": { "200": { "description": "Block type", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string" }, "summary": { "type": "string" }, "config_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "needs_options": { "type": "boolean" }, "answered_by": { "type": "string" }, "config_schema": {}, "public_block": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, "answer": {} }, "required": [ "type", "summary", "config_hint", "needs_options", "answered_by", "config_schema", "public_block", "answer" ], "additionalProperties": {} } } } }, "404": { "description": "No such block type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "type", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/events": { "get": { "operationId": "getV1Events", "tags": [ "v1" ], "summary": "The webhook event catalog", "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "also_matches": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "also_matches" ] } } }, "required": [ "events" ] } } } } }, "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/me": { "get": { "operationId": "getV1Me", "tags": [ "v1" ], "summary": "Who this key is, what it may do, and what is left of the plan", "responses": { "200": { "description": "Key identity", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization_id": { "type": "string" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "scopes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "id", "type", "mode", "scopes" ] }, "scope_vocabulary": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "plan": { "type": "string" }, "limits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "organization_id", "key", "scope_vocabulary" ], "additionalProperties": {} } } } } }, "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms": { "get": { "operationId": "getV1Forms", "parameters": [ { "in": "query", "name": "status", "schema": { "default": "all", "type": "string", "enum": [ "draft", "published", "archived", "all" ] } }, { "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } } ], "tags": [ "v1" ], "summary": "List forms", "responses": { "200": { "description": "A page of forms", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "published": { "type": "boolean", "description": "Whether the form is live and taking responses" }, "created_at": { "type": "number" }, "updated_at": { "type": "number" } }, "required": [ "id", "title", "slug", "status", "published", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "400": { "description": "Malformed cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] }, "post": { "operationId": "postV1Forms", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "doc": {} }, "required": [ "title" ] } } } }, "tags": [ "v1" ], "summary": "Create a form", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "published": { "type": "boolean", "description": "Whether the form is live and taking responses" }, "created_at": { "type": "number" }, "updated_at": { "type": "number" } }, "required": [ "id", "title", "slug", "status", "published", "created_at", "updated_at" ] } } } }, "422": { "description": "The document is invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}": { "get": { "operationId": "getV1FormsById", "tags": [ "v1" ], "summary": "Read a form: its public config, or the document behind it", "description": "Without `view`, this answers the published form exactly as a respondent receives it. A form with no published version has only a draft, so that is what comes back instead -- the same body as `view=document`, with `status` saying which you are looking at. Pass `view=document` to read the draft of a form that is already live.", "parameters": [ { "name": "view", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "public", "document" ], "default": "public" }, "description": "`document` returns the editable working draft, which is the only view a form has before it is published." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "The published config, or the working draft when there is no published version", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} } }, "required": [ "id", "slug", "status", "doc" ], "additionalProperties": {} }, { "type": "object", "properties": { "slug": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} } } }, "required": [ "slug", "blocks" ], "additionalProperties": {} } ] } } } }, "404": { "description": "Not found, or not published and no `view=document` was asked for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] }, "delete": { "operationId": "deleteV1FormsById", "tags": [ "v1" ], "summary": "Delete a form: it moves to the Archive and is deleted for good after 30 days", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "boolean" } }, "required": [ "ok", "deleted" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/doc": { "put": { "operationId": "putV1FormsByIdDoc", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": {} }, "required": [ "doc" ] } } } }, "tags": [ "v1" ], "summary": "Replace the working document, returning lint issues", "responses": { "200": { "description": "Saved, with issues", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" }, "refs": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "code", "message" ] } } }, "required": [ "ok", "issues" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/unpublish": { "post": { "operationId": "postV1FormsByIdUnpublish", "tags": [ "v1" ], "summary": "Take a published form off the air, keeping its version and responses", "responses": { "200": { "description": "Unpublished", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The form is not published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:publish", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/publish": { "post": { "operationId": "postV1FormsByIdPublish", "tags": [ "v1" ], "summary": "Publish the working document as a new immutable version", "responses": { "200": { "description": "Published", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "number" }, "versionId": { "type": "string" }, "stripped": { "type": "array", "items": {} } }, "required": [ "ok", "version", "versionId", "stripped" ] } } } }, "402": { "description": "A plan limit refuses the publish", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Lint errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:publish", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/archive/forms": { "get": { "operationId": "getV1ArchiveForms", "tags": [ "v1" ], "summary": "List archived forms", "description": "Deleted forms stay here for 30 days, restorable, then are deleted for good with their responses.", "responses": { "200": { "description": "Archived forms, most recently archived first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "workspace_id": { "type": "string" }, "archived_at": { "type": "number" }, "purge_at": { "type": "number", "description": "When the form and everything it collected is deleted for good" }, "responses": { "type": "number" }, "partials": { "type": "number" }, "conversations": { "type": "number" }, "uploads": { "type": "number" } }, "required": [ "id", "title", "workspace_id", "archived_at", "purge_at", "responses", "partials", "conversations", "uploads" ] } } }, "required": [ "data" ] } } } } }, "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/archive/forms/{id}/restore": { "post": { "operationId": "postV1ArchiveFormsByIdRestore", "tags": [ "v1" ], "summary": "Restore an archived form, as a draft", "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "404": { "description": "Not in the Archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/archive/forms/{id}": { "delete": { "operationId": "deleteV1ArchiveFormsById", "tags": [ "v1" ], "summary": "Delete an archived form for good, now", "description": "Removes the form with every response, conversation and upload within a few minutes. Cannot be undone.", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "boolean" } }, "required": [ "ok", "deleted" ] } } } }, "404": { "description": "Not in the Archive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/analytics": { "get": { "operationId": "getV1FormsByIdAnalytics", "tags": [ "v1" ], "summary": "Counts, per-question funnel and answer distributions", "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "default": "all" }, "description": "Only responses from this channel (`chat`, `embed`, `api`), or `all`." }, { "name": "includeTest", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "`1` counts test-mode responses too. A test key always does." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Analytics", "content": { "application/json": { "schema": { "type": "object", "properties": { "views": { "type": "number" }, "starts": { "type": "number" }, "completed": { "type": "number" }, "abandoned": { "type": "number" }, "inProgress": { "type": "number" }, "startsWithContext": { "type": "number" }, "avgDurationMs": { "type": "number" }, "medianDurationMs": { "type": "number" }, "completionRate": { "type": "number" }, "perBlock": { "type": "array", "items": { "type": "object", "properties": { "blockRef": { "type": "string" }, "blockType": { "type": "string" }, "title": { "type": "string" }, "answered": { "type": "number" }, "answerRate": { "type": "number" }, "dropOff": { "type": "number" } }, "required": [ "blockRef", "blockType", "title", "answered", "answerRate", "dropOff" ] } }, "distributions": { "type": "array", "items": { "type": "object", "properties": { "blockRef": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" }, "answered": { "type": "number" }, "options": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "multi": { "type": "boolean" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "count": { "type": "number" } }, "required": [ "value", "count" ] } }, "numericSummary": { "anyOf": [ { "type": "object", "properties": { "avg": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "median": { "type": "number" } }, "required": [ "avg", "min", "max", "median" ] }, { "type": "null" } ] }, "samples": { "type": "array", "items": { "type": "string" } }, "ranking": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "avgRank": { "type": "number" } }, "required": [ "label", "avgRank" ] } }, "matrix": { "anyOf": [ { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "string" } }, "cols": { "type": "array", "items": { "type": "string" } }, "counts": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } } }, "required": [ "rows", "cols", "counts" ] }, { "type": "null" } ] }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } } }, "required": [ "blockRef", "title", "type", "answered", "options", "multi", "values", "numericSummary", "samples", "ranking", "matrix", "timeline" ] } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "views": { "type": "number" }, "starts": { "type": "number" }, "completed": { "type": "number" } }, "required": [ "date", "views", "starts", "completed" ] } }, "bySource": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "count": { "type": "number" } }, "required": [ "source", "count" ] } }, "byCountry": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "count": { "type": "number" } }, "required": [ "country", "count" ] } }, "byDevice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "places": { "type": "array", "items": { "type": "object", "properties": { "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lat": { "type": "number" }, "lon": { "type": "number" }, "count": { "type": "number" }, "completed": { "type": "number" } }, "required": [ "country", "region", "city", "lat", "lon", "count", "completed" ] } }, "byBrowser": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "byOs": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "byChannel": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "byReferrer": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "byCampaign": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" }, "completed": { "type": "number" } }, "required": [ "label", "count", "completed" ] } }, "byDeviceType": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" }, "completed": { "type": "number" } }, "required": [ "label", "count", "completed" ] } }, "byLanguage": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" }, "completed": { "type": "number" } }, "required": [ "label", "count", "completed" ] } }, "byWeekHour": { "type": "array", "items": { "type": "array", "items": { "type": "number" } } }, "durationBuckets": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "count": { "type": "number" } }, "required": [ "label", "count" ] } }, "aiFallbacks": { "type": "object", "properties": { "calls": { "type": "number" }, "sessions": { "type": "number" }, "reasons": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "count": { "type": "number" } }, "required": [ "code", "count" ] } } }, "required": [ "calls", "sessions", "reasons" ] }, "locked": { "type": "array", "items": { "type": "string" } } }, "required": [ "views", "starts", "completed", "abandoned", "inProgress", "avgDurationMs", "medianDurationMs", "completionRate", "perBlock", "distributions", "daily", "bySource", "byCountry", "byDevice", "durationBuckets" ], "additionalProperties": {} } } } }, "402": { "description": "The per-question detail needs a plan that includes it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "analytics:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/analytics/overview": { "get": { "operationId": "getV1AnalyticsOverview", "parameters": [ { "name": "tz", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "Minutes east of UTC that a day starts in, e.g. `330` for India. View counts are always UTC days." } ], "tags": [ "v1" ], "summary": "Headline numbers across every form: the last 7 days against the 7 before", "responses": { "200": { "description": "Overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "days": { "type": "number" }, "today": { "type": "number" }, "kpis": { "type": "object", "properties": { "responses": { "type": "object", "properties": { "value": { "type": "number" }, "previous": { "type": "number" } }, "required": [ "value", "previous" ] }, "views": { "type": "object", "properties": { "value": { "type": "number" }, "previous": { "type": "number" } }, "required": [ "value", "previous" ] }, "completionRate": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previous": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "value", "previous" ] }, "partial": { "type": "object", "properties": { "value": { "type": "number" }, "previous": { "type": "number" } }, "required": [ "value", "previous" ] }, "medianMs": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "previous": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "value", "previous" ] } }, "required": [ "responses", "views", "completionRate", "partial", "medianMs" ] }, "series": { "type": "object", "properties": { "responses": { "type": "array", "items": { "type": "number" } }, "views": { "type": "array", "items": { "type": "number" } }, "completionRate": { "type": "array", "items": { "type": "number" } }, "partial": { "type": "array", "items": { "type": "number" } } }, "required": [ "responses", "views", "completionRate", "partial" ] }, "locked": { "type": "array", "items": { "type": "string" } } }, "required": [ "days", "today", "kpis", "series", "locked" ] } } } } }, "x-required-scope": "analytics:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/followup-analytics": { "get": { "operationId": "getV1FormsByIdFollowupAnalytics", "tags": [ "v1" ], "summary": "Follow-up recovery report (sent, clicked, recovered, holdout lift)", "responses": { "200": { "description": "Recovery report", "content": { "application/json": { "schema": { "type": "object", "properties": { "everScheduled": { "type": "boolean" }, "sent": { "type": "number" }, "pending": { "type": "number" }, "clicked": { "type": "number" }, "recovered": { "type": "number" }, "clickRate": { "type": "number" }, "recoveryRate": { "type": "number" }, "byStep": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "number" }, "sent": { "type": "number" }, "clicked": { "type": "number" }, "recovered": { "type": "number" } }, "required": [ "step", "sent", "clicked", "recovered" ] } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "sent": { "type": "number" }, "recovered": { "type": "number" } }, "required": [ "date", "sent", "recovered" ] } }, "holdout": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "liftPoints": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "everScheduled", "sent", "pending", "clicked", "recovered", "clickRate", "recoveryRate", "byStep", "daily", "holdout", "liftPoints" ], "additionalProperties": {} } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "analytics:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/settings": { "get": { "operationId": "getV1FormsByIdSettings", "tags": [ "v1" ], "summary": "Every setting a form has, by key, with its current value", "description": "The settings you can change with `PATCH /v1/forms/{id}/settings`: colours and fonts, the interviewer's tone and goal, who can respond, when the form closes, emails, sharing and embedding. Each carries the builder's label, where it lives in the builder, the values it takes, and `locked` when your plan does not include it.", "responses": { "200": { "description": "The settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "section": { "type": "string" }, "sectionLabel": { "type": "string" }, "label": { "type": "string" }, "where": { "type": "string" }, "format": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "min": { "type": "number" }, "max": { "type": "number" }, "maxLength": { "type": "number" }, "maxItems": { "type": "number" }, "clearable": { "type": "boolean" }, "hint": { "type": "string" }, "value": {}, "locked": { "type": "object", "properties": { "feature": { "type": "string" }, "plan": { "type": "string" } }, "required": [ "feature", "plan" ] } }, "required": [ "key", "section", "sectionLabel", "label", "where", "format", "value" ], "additionalProperties": {} } } }, "required": [ "settings" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] }, "patch": { "operationId": "patchV1FormsByIdSettings", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "changes": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string", "maxLength": 10000 } }, "required": [ "key", "value" ] }, "description": "Each setting by its key from GET /v1/forms/{id}/settings, with the new value as text. Empty text clears a clearable setting." }, "utcOffsetMinutes": { "description": "For a date written without a zone: minutes behind UTC, as JavaScript's Date#getTimezoneOffset() reports it.", "type": "integer", "minimum": -900, "maximum": 900 } }, "required": [ "changes" ] } } } }, "tags": [ "v1" ], "summary": "Change a form's settings by key", "description": "Changes the working document; nothing is live until `POST /v1/forms/{id}/publish`. Every value is checked: one that does not parse is listed in `rejected` with the reason and nothing else in the call is held back. A setting your plan does not include comes back in `changes` with `locked` and is not applied. 422 when nothing in the call could be applied.", "responses": { "200": { "description": "What changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "changes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "section": { "type": "string" }, "label": { "type": "string" }, "where": { "type": "string" }, "format": { "type": "string" }, "before": {}, "after": {}, "locked": { "type": "object", "properties": { "feature": { "type": "string" } }, "required": [ "feature" ] } }, "required": [ "key", "section", "label", "where", "format", "before", "after" ], "additionalProperties": {} } }, "rejected": { "type": "array", "items": { "type": "string" } } }, "required": [ "changes", "rejected" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "422": { "description": "Nothing could be applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/templates": { "get": { "operationId": "getV1Templates", "tags": [ "v1" ], "summary": "List the official form templates, most used first", "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "blurb": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "icon": { "type": "string" }, "accent": { "type": "string" }, "blockCount": { "type": "number" }, "estMinutes": { "type": "number" }, "usageCount": { "type": "number" } }, "required": [ "slug", "title", "category", "description", "blurb", "tags", "icon", "accent", "blockCount", "estMinutes", "usageCount" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } } }, "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/templates/{slug}": { "get": { "operationId": "getV1TemplatesBySlug", "tags": [ "v1" ], "summary": "One template, including the document it would create", "description": "Read this before `POST /v1/templates/{slug}/use` if you want to see or adapt the questions rather than take them as they are.", "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "description": { "type": "string" }, "blurb": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "icon": { "type": "string" }, "accent": { "type": "string" }, "blockCount": { "type": "number" }, "estMinutes": { "type": "number" }, "usageCount": { "type": "number" }, "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} } }, "required": [ "slug", "title", "category", "description", "blurb", "tags", "icon", "accent", "blockCount", "estMinutes", "usageCount", "doc" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "slug", "required": true } ], "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/templates/{slug}/use": { "post": { "operationId": "postV1TemplatesBySlugUse", "parameters": [ { "in": "query", "name": "workspace", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "slug", "required": true } ], "tags": [ "v1" ], "summary": "Create a draft form from a template", "description": "Creates a draft, exactly as `POST /v1/forms` does. Publish it when you are ready. The form lands in the organization's first workspace, which is not something an API key can choose: `/v1` exposes no workspace endpoint.", "responses": { "200": { "description": "The created form", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "published": { "type": "boolean", "description": "Whether the form is live and taking responses" }, "created_at": { "type": "number" }, "updated_at": { "type": "number" } }, "required": [ "id", "title", "slug", "status", "published", "created_at", "updated_at" ] } } } }, "402": { "description": "A plan limit refuses another form", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Template or workspace not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/versions": { "get": { "operationId": "getV1FormsByIdVersions", "tags": [ "v1" ], "summary": "Every published version of a form, newest first", "description": "Each version carries the number of completed responses recorded against it. A version nobody answered can be replaced freely; one with responses behind it is the schema those answers were recorded against.", "responses": { "200": { "description": "Versions", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "version": { "type": "number" }, "versionId": { "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "type": "number" }, "authorLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changeCount": { "type": "number" }, "isActive": { "type": "boolean" }, "responses": { "type": "number" } }, "required": [ "version", "versionId", "note", "publishedAt", "authorLabel", "changeCount", "isActive", "responses" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/versions/{version}": { "get": { "operationId": "getV1FormsByIdVersionsByVersion", "parameters": [ { "in": "query", "name": "compare", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "version", "required": true } ], "tags": [ "v1" ], "summary": "One published version, optionally diffed against another", "description": "Pass `compare` with another version number to get the list of changes between them.", "responses": { "200": { "description": "The published document, plus a diff when `compare` is given", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number" }, "versionId": { "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "type": "number" }, "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} }, "comparedTo": { "type": "number" }, "changes": { "type": "array", "items": {} }, "summary": { "type": "string" } }, "required": [ "version", "versionId", "note", "publishedAt", "doc", "changes", "summary" ], "additionalProperties": {} } } } }, "404": { "description": "No such form or version", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/versions/{version}/restore": { "post": { "operationId": "postV1FormsByIdVersionsByVersionRestore", "tags": [ "v1" ], "summary": "Restore a published version into the working document", "description": "Writes the draft, not the live form, so respondents see nothing change until you publish. Returns the restored document and what it changed.", "responses": { "200": { "description": "The draft now matches that version", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "version": { "type": "number" }, "summary": { "type": "string" }, "changes": { "type": "array", "items": {} }, "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} } }, "required": [ "ok", "version", "summary", "changes", "doc" ], "additionalProperties": {} } } } }, "404": { "description": "No such form or version", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "422": { "description": "That version cannot be read", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "version", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/ai/generate-form": { "post": { "operationId": "postV1AiGenerateForm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 5, "maxLength": 2000 }, "questionCount": { "type": "integer", "minimum": 2, "maximum": 50 }, "clarifications": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 300 }, "answer": { "type": "string", "maxLength": 500 } }, "required": [ "question", "answer" ] } }, "workspaceId": { "type": "string" }, "reserveKnowledge": { "type": "integer", "minimum": 0, "maximum": 100 }, "utcOffsetMinutes": { "type": "integer", "minimum": -900, "maximum": 900 } }, "required": [ "prompt" ] } } } }, "tags": [ "v1" ], "summary": "Generate a form document from a natural-language prompt", "description": "Returns a document and its lint issues **without saving anything**. Pass the result to `POST /v1/forms` to keep it. Consumes one `ai_generations` unit and the tokens it costs, charged only when a usable document comes back. If you are already driving this from a model of your own, writing the document yourself and posting it to `/v1/forms` costs you nothing here. Settings the prompt asks for (\"a dark, playful form that closes on the 30th\") are set on `doc` and listed in `settings`, one entry per setting with its value before and after; one marked `locked` is not on your plan and was left at its default.", "responses": { "200": { "description": "The generated document, its lint issues, the tokens spent, and the settings it set", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} }, "issues": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" }, "refs": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "code", "message" ] } }, "tokens": { "type": "number" }, "settings": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "section": { "type": "string" }, "label": { "type": "string" }, "where": { "type": "string" }, "format": { "type": "string" }, "before": {}, "after": {}, "locked": { "type": "object", "properties": { "feature": { "type": "string" } }, "required": [ "feature" ] } }, "required": [ "key", "section", "label", "where", "format", "before", "after" ], "additionalProperties": {} } } }, "required": [ "doc", "issues", "tokens" ] } } } }, "402": { "description": "Out of generations for this billing period", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the ai:generate scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "502": { "description": "Generation failed after retries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "AI is not configured on this deployment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "ai:generate", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/ai/edit-form": { "post": { "operationId": "postV1AiEditForm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "formId": { "type": "string" }, "prompt": { "type": "string", "minLength": 3, "maxLength": 1000 }, "history": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "role", "text" ] } }, "count": { "type": "integer", "minimum": 1, "maximum": 10 }, "utcOffsetMinutes": { "type": "integer", "minimum": -900, "maximum": 900 }, "clarifications": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 300 }, "answer": { "type": "string", "maxLength": 500 } }, "required": [ "question", "answer" ] } } }, "required": [ "formId", "prompt" ] } } } }, "tags": [ "v1" ], "summary": "Ask a model to change an existing form: add, edit or remove questions and rewire the flow", "description": "Returns the proposed document **without saving it**. Send it to `PUT /v1/forms/{id}/doc` to keep it. An edit may add no questions at all: most requests about a working form change the routing rather than the wording. Pass `history` (oldest first) when this is a follow-up, or the model cannot resolve 'also', 'it' or 'instead'. A request about the form's settings (its colours, the interviewer's tone, a closing date) comes back in `settings`, one entry per setting with its value before and after, already applied to `doc` unless it is marked `locked` because the plan does not include it. A question about how to do something comes back as `answer`, with no `doc`.", "responses": { "200": { "description": "The proposed document and what changed", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} }, "issues": { "type": "array", "items": { "type": "object", "properties": { "level": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "path": { "type": "string" }, "refs": { "type": "array", "items": { "type": "string" } } }, "required": [ "level", "code", "message" ] } } }, "required": [ "doc" ], "additionalProperties": {} } } } }, "402": { "description": "Out of generations for this billing period", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "403": { "description": "The key lacks the ai:generate scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "422": { "description": "The request would change nothing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "Generation failed after retries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "ai:generate", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/ai/clarify-form": { "post": { "operationId": "postV1AiClarifyForm", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 3, "maxLength": 2000 }, "formId": { "type": "string" }, "history": { "default": [], "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "role", "text" ] } } }, "required": [ "prompt" ] } } } }, "tags": [ "v1" ], "summary": "Ask what a form request leaves open, before generating from it", "description": "Returns up to three questions whose answers would change the form, and **usually returns none**, which is the intended answer rather than a failure. Worth calling when a person is going to see the result: a request that asks to take a payment but names no UPI id, or to branch by plan without naming the plans, produces a form with a hole in it that only they can fill.\n\nFeed the answers back as `clarifications` on `POST /v1/ai/generate-form`. Skipping this endpoint entirely is fine; generation does not require it.\n\nRuns on the cheapest tier and is not charged as a generation, being a question about a form rather than a form, though its tokens are still counted.", "responses": { "200": { "description": "Questions worth asking, oldest concern first. An empty list means the request is answerable as it stands.", "content": { "application/json": { "schema": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "why": { "type": "string" }, "kind": { "type": "string", "enum": [ "choice", "text" ] }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "question", "why", "kind", "options" ] } } }, "required": [ "questions" ] } } } }, "403": { "description": "The key lacks the ai:generate scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "x-required-scope": "ai:generate", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/import": { "post": { "operationId": "postV1Import", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "minLength": 4, "maxLength": 2000 } }, "required": [ "url" ] } } } }, "tags": [ "v1" ], "summary": "Convert a public Typeform, Google Form or Tally form into a form document", "description": "Reads the form behind a public link and converts its questions, options, required fields, endings and jumps. Returns the document **without saving it**, plus a report of anything that could not be copied (payments, scores, rules that test a different question). Post the document to `POST /v1/forms` to keep it. The source form must open without signing in.", "responses": { "200": { "description": "The converted document and its report", "content": { "application/json": { "schema": { "type": "object", "properties": { "doc": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "title": { "type": "string" }, "description": { "type": "string" }, "blocks": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endings": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "endingRules": { "type": "array", "items": {} }, "logic": { "type": "array", "items": {} }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } }, "variables": { "type": "array", "items": {} }, "hiddenFields": { "type": "array", "items": {} }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "theme": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "embed": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "schemaVersion", "title", "blocks", "endings", "endingRules", "logic" ], "additionalProperties": {} }, "report": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "typeform", "google_forms", "tally", "jotform", "youform", "website" ] }, "sourceUrl": { "type": "string" }, "questions": { "type": "number" }, "branches": { "type": "number" }, "endings": { "type": "number" }, "notCopied": { "type": "array", "items": { "type": "string" } }, "closed": { "type": "boolean" }, "outline": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "title", "type", "required" ] } } }, "required": [ "provider", "sourceUrl", "questions", "branches", "endings", "notCopied", "closed", "outline" ] } }, "required": [ "doc", "report" ], "additionalProperties": {} } } } }, "403": { "description": "The key lacks the form:write scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "422": { "description": "The link cannot be imported; `error.code` says why", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/integrations": { "get": { "operationId": "getV1FormsByIdIntegrations", "tags": [ "v1" ], "summary": "A form's non-webhook integrations", "description": "Currently just the spreadsheet feed, if one exists. An empty array means no feed has been created.", "responses": { "200": { "description": "Integrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "feedUrl": { "type": "string" }, "includePartials": { "type": "boolean" } }, "required": [ "id", "provider", "status", "createdAt" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/integrations/spreadsheet": { "put": { "operationId": "putV1FormsByIdIntegrationsSpreadsheet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "includePartials": { "type": "boolean" }, "rotate": { "type": "boolean" } } } } } }, "tags": [ "v1" ], "summary": "Create, update or rotate the spreadsheet feed", "description": "Idempotent by nature, because there is one feed per form, which is why this is a PUT. The returned `feedUrl` is a live CSV a spreadsheet can re-read on a schedule; it is unauthenticated, so the URL is the whole credential. Send `rotate: true` to invalidate the previous one.", "responses": { "200": { "description": "The feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "number" }, "feedUrl": { "type": "string" }, "includePartials": { "type": "boolean" } }, "required": [ "id", "provider", "status", "createdAt" ] } } } }, "402": { "description": "Including unfinished responses needs a plan that allows it", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] }, "delete": { "operationId": "deleteV1FormsByIdIntegrationsSpreadsheet", "tags": [ "v1" ], "summary": "Revoke the spreadsheet feed", "description": "The URL stops working immediately. Any spreadsheet reading it will start failing to refresh.", "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/payment-accounts": { "get": { "operationId": "getV1PaymentAccounts", "tags": [ "v1" ], "summary": "List connected payment gateway accounts", "description": "The Cashfree, Razorpay and Stripe accounts this organization has connected for verified payments. Credentials are never returned. `formsUsing` counts forms whose working document names the account.", "responses": { "200": { "description": "Accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "credentialKind": { "type": "string", "enum": [ "oauth", "connect" ] }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "label": { "type": "string" }, "providerAccountId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "needs_reconnect", "revoked", "disconnected" ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currencies": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "number" }, "formsUsing": { "type": "number" }, "connectedBy": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "email" ] }, { "type": "null" } ] }, "isDefault": { "type": "boolean" } }, "required": [ "id", "provider", "credentialKind", "environment", "label", "providerAccountId", "status", "lastError", "currencies", "createdAt" ] } }, "enabled": { "type": "boolean" }, "providers": { "type": "object", "properties": { "cashfree": { "type": "object", "properties": { "configured": { "type": "boolean" } }, "required": [ "configured" ] }, "razorpay": { "type": "object", "properties": { "configured": { "type": "boolean" } }, "required": [ "configured" ] }, "stripe": { "type": "object", "properties": { "configured": { "type": "boolean" } }, "required": [ "configured" ] } }, "required": [ "cashfree", "razorpay", "stripe" ] } }, "required": [ "accounts", "enabled", "providers" ] } } } }, "403": { "description": "Missing payment:read", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "x-required-scope": "payment:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/payment-accounts/oauth/{provider}/start": { "post": { "operationId": "postV1PaymentAccountsOauthByProviderStart", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "returnTo": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "returnTo" ] } } } }, "tags": [ "v1" ], "summary": "Start connecting a Cashfree, Razorpay or Stripe account", "description": "Returns the gateway's consent URL. It must be opened in a browser signed in to chatform as the user who created this key; the state is single-use and expires in ten minutes. `returnTo` must be a page on the chatform app.", "responses": { "200": { "description": "Consent URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } } } }, "402": { "description": "Plan does not include collecting payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "403": { "description": "Missing payment:write, or verified payments are not enabled", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "422": { "description": "returnTo is not a page on the app", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "provider", "required": true } ], "x-required-scope": "payment:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/payment-accounts/cashfree/onboard": { "post": { "operationId": "postV1PaymentAccountsCashfreeOnboard", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 200, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "minLength": 8, "maxLength": 20 }, "businessName": { "type": "string", "minLength": 2, "maxLength": 100 }, "businessType": { "type": "string", "minLength": 2, "maxLength": 60 }, "website": { "type": "string", "maxLength": 250, "format": "uri" }, "signatoryName": { "type": "string", "minLength": 2, "maxLength": 100 }, "returnTo": { "type": "string", "maxLength": 1000 } }, "required": [ "email", "phone", "businessName", "businessType" ] } } } }, "tags": [ "v1" ], "summary": "Create a Cashfree account for a business that has none", "description": "Returns the Cashfree KYC link, or `{ useOAuth: true }` when the email already has a Cashfree account.", "responses": { "200": { "description": "Onboarding link, or a pointer to OAuth", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "onboardingUrl": { "type": "string" } }, "required": [ "onboardingUrl" ] }, { "type": "object", "properties": { "useOAuth": { "type": "boolean", "const": true } }, "required": [ "useOAuth" ] } ] } } } }, "402": { "description": "Plan does not include collecting payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "x-required-scope": "payment:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/payment-accounts/{id}": { "patch": { "operationId": "patchV1PaymentAccountsById", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "isDefault": { "type": "boolean", "const": true } } } } } }, "tags": [ "v1" ], "summary": "Rename a payment account, or make it the default", "description": "`label` sets the name the account is shown under in the builder. `isDefault: true` makes it the account new verified-checkout questions start on. Nothing changes at the gateway.", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "payment:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] }, "delete": { "operationId": "deleteV1PaymentAccountsById", "tags": [ "v1" ], "summary": "Disconnect a payment account", "description": "Revokes chatform's access at the gateway, then wipes the stored credentials. Forms still pointing at the account stop accepting payments until another account is chosen.", "responses": { "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "payment:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/payments": { "get": { "operationId": "getV1FormsByIdPayments", "parameters": [ { "in": "query", "name": "status", "schema": { "default": "all", "type": "string", "enum": [ "created", "paid", "failed", "expired", "refunded", "superseded", "all" ] } }, { "in": "query", "name": "response_id", "schema": { "type": "string", "maxLength": 40 } }, { "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } }, { "in": "query", "name": "cursor", "schema": { "type": "string" } }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "tags": [ "v1" ], "summary": "List a form's payment attempts, newest first", "description": "Every checkout opened on a verified payment block, including the ones that never became an answer — a payment that arrived after the respondent left, a duplicate from a second tab, a failure. `status` defaults to `all`. Amounts are given both in minor units (`amount_minor`, what the gateway charged) and major units. Pass `next_cursor` back as `cursor` for the next page.", "responses": { "200": { "description": "A page of payment attempts", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "payment" }, "form_id": { "type": "string" }, "block_ref": { "type": "string" }, "response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider": { "type": "string" }, "environment": { "type": "string", "enum": [ "test", "live" ] }, "mode": { "type": "string", "enum": [ "test", "live" ] }, "status": { "type": "string", "enum": [ "created", "paid", "failed", "expired", "refunded", "superseded" ] }, "duplicate": { "type": "boolean" }, "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "amount": { "type": "number" }, "currency": { "type": "string" }, "provider_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "provider_payment_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dashboard_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failure_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settled_to_response": { "type": "boolean" }, "payment_account_id": { "type": "string" }, "created_at": { "type": "number" }, "updated_at": { "type": "number" }, "paid_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "object", "form_id", "block_ref", "response_id", "provider", "environment", "mode", "status", "duplicate", "amount_minor", "amount", "currency", "provider_order_id", "provider_payment_id", "dashboard_url", "failure_reason", "settled_to_response", "payment_account_id", "created_at", "updated_at", "paid_at", "expires_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "400": { "description": "Malformed cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "x-required-scope": "response:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/webhooks": { "get": { "operationId": "getV1Webhooks", "tags": [ "v1" ], "summary": "List webhook endpoints", "parameters": [ { "name": "formId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only endpoints for this form, plus the organization-wide ones." } ], "responses": { "200": { "description": "Endpoints", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "formId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "secretPreview": { "type": "string" } }, "required": [ "id", "url", "events", "formId", "active", "consecutiveFailures", "createdAt", "secretPreview" ], "additionalProperties": {} } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } } }, "x-required-scope": "webhook:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] }, "post": { "operationId": "postV1Webhooks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "events": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "string" } }, "formId": { "type": "string", "maxLength": 64 } }, "required": [ "url", "events" ] } } } }, "tags": [ "v1" ], "summary": "Create a webhook endpoint. The signing secret is returned ONCE", "responses": { "201": { "description": "Created, with the signing secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "formId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "secretPreview": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "url", "events", "formId", "active", "consecutiveFailures", "createdAt", "secretPreview", "secret" ], "additionalProperties": {} } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unknown event name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "webhook:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/webhooks/stats": { "get": { "operationId": "getV1WebhooksStats", "tags": [ "v1" ], "summary": "Delivery queue status: pending, failed and delivered in the last 24 hours, per endpoint", "parameters": [ { "name": "formId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only endpoints for this form, plus the organization-wide ones." } ], "responses": { "200": { "description": "Counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "object", "properties": { "pending": { "type": "number" }, "failed": { "type": "number" }, "delivered24h": { "type": "number" }, "lastDeliveredAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "pending", "failed", "delivered24h", "lastDeliveredAt" ] }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "pending": { "type": "number" }, "failed": { "type": "number" }, "delivered24h": { "type": "number" }, "lastDeliveredAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "webhookId": { "type": "string" } }, "required": [ "pending", "failed", "delivered24h", "lastDeliveredAt", "webhookId" ] } } }, "required": [ "total", "endpoints" ] } } } } }, "x-required-scope": "webhook:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/webhooks/{id}": { "patch": { "operationId": "patchV1WebhooksById", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ] } } } }, "tags": [ "v1" ], "summary": "Turn an endpoint on or off. Turning it on clears its failure count", "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "formId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "consecutiveFailures": { "type": "number" }, "createdAt": { "type": "number" }, "secretPreview": { "type": "string" } }, "required": [ "id", "url", "events", "formId", "active", "consecutiveFailures", "createdAt", "secretPreview" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "webhook:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] }, "delete": { "operationId": "deleteV1WebhooksById", "tags": [ "v1" ], "summary": "Delete a webhook endpoint", "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "deleted": { "type": "boolean" } }, "required": [ "ok", "deleted" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "webhook:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "getV1WebhooksByIdDeliveries", "tags": [ "v1" ], "summary": "Recent deliveries with every attempt, for working out why an endpoint is quiet. Filter with ?status=pending|failed|success", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "failed", "success" ] }, "description": "Only deliveries in this state. Any other value is ignored." }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "eventId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "success", "failed" ] }, "attempt": { "type": "number" }, "maxAttempts": { "type": "number" }, "responseStatus": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nextAttemptAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "createdAt": { "type": "number" }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "number" }, "status": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "responseBody": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "at": { "type": "number" } }, "required": [ "attempt", "status", "error", "responseBody", "durationMs", "at" ] } } }, "required": [ "id", "eventId", "event", "status", "attempt", "maxAttempts", "responseStatus", "lastError", "nextAttemptAt", "deliveredAt", "createdAt", "attempts" ], "additionalProperties": {} } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "webhook:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "operationId": "postV1WebhooksByIdDeliveriesByDeliveryIdReplay", "tags": [ "v1" ], "summary": "Replay one delivery", "responses": { "200": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "queued": { "type": "boolean" } }, "required": [ "ok", "queued" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Nothing to replay", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "deliveryId", "required": true } ], "x-required-scope": "webhook:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/webhooks/{id}/retry-failed": { "post": { "operationId": "postV1WebhooksByIdRetryFailed", "tags": [ "v1" ], "summary": "Send every failed delivery of an endpoint again (up to 500)", "responses": { "200": { "description": "Queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "queued": { "type": "number" } }, "required": [ "ok", "queued" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "webhook:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/exports": { "post": { "operationId": "postV1FormsByIdExports", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "default": "csv", "type": "string", "enum": [ "csv", "json" ] }, "status": { "maxItems": 6, "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "maxLength": 20 }, "mode": { "type": "string", "enum": [ "live", "test", "all" ] }, "created_after": { "type": "number" }, "created_before": { "type": "number" } } } } } }, "tags": [ "v1" ], "summary": "Start an export of a form's responses", "description": "Returns immediately with a queued export. Poll `GET /v1/exports/{id}` until `status` is `ready`, then follow `download_url`.", "responses": { "202": { "description": "Export queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "export" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed" ] }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "row_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "object", "form_id", "status", "format", "row_count", "bytes", "error", "created_at", "completed_at", "expires_at", "download_url", "download_expires_at" ] } } } }, "402": { "description": "Exporting unfinished responses needs a plan that includes them", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/exports/{id}": { "get": { "operationId": "getV1ExportsById", "tags": [ "v1" ], "summary": "Check an export and get its download link", "description": "Poll until `status` is `ready`, then follow `download_url`. A `failed` export carries the reason in `error`. The link is re-minted on every read, so read again rather than storing one.", "responses": { "200": { "description": "The export", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "export" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed" ] }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "row_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "object", "form_id", "status", "format", "row_count", "bytes", "error", "created_at", "completed_at", "expires_at", "download_url", "download_expires_at" ] } } } }, "404": { "description": "Export not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/exports/{id}/content": { "get": { "operationId": "getV1ExportsByIdContent", "parameters": [ { "in": "query", "name": "offset", "schema": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "in": "query", "name": "max_bytes", "schema": { "default": 200000, "type": "integer", "minimum": 1000, "maximum": 200000 } }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "tags": [ "v1" ], "summary": "Read a ready export's contents", "description": "The export's text, a slice at a time, under the same API key, for a caller that cannot fetch `download_url` (an agent sandbox that only reaches allow-listed hosts, say). Read from `offset` 0 and pass `next_offset` back until it is null; the slices join into the exact file.", "responses": { "200": { "description": "A slice of the export", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "export_content" }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "offset": { "type": "number" }, "next_offset": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "total_bytes": { "type": "number" }, "content": { "type": "string" } }, "required": [ "id", "object", "format", "offset", "next_offset", "total_bytes", "content" ] } } } }, "404": { "description": "Export not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "The export is not ready yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/exports": { "get": { "operationId": "getV1Exports", "parameters": [ { "in": "query", "name": "form_id", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "default": 25, "type": "integer", "minimum": 1, "maximum": 100 } } ], "tags": [ "v1" ], "summary": "List recent exports", "description": "Newest first, optionally narrowed to one form. Exports are deleted 24 hours after they are requested, so this is a short window rather than a history.", "responses": { "200": { "description": "Exports, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "export" }, "form_id": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "running", "ready", "failed" ] }, "format": { "type": "string", "enum": [ "csv", "json" ] }, "row_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "bytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "number" }, "completed_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "download_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "download_expires_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id", "object", "form_id", "status", "format", "row_count", "bytes", "error", "created_at", "completed_at", "expires_at", "download_url", "download_expires_at" ] } }, "has_more": { "type": "boolean" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "data", "has_more", "next_cursor" ] } } } } }, "x-required-scope": "response:export", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/files/{id}": { "get": { "operationId": "getV1FilesById", "tags": [ "v1" ], "summary": "A respondent's uploaded file, with a short-lived download link", "description": "File-upload answers carry a `fileId`. This resolves one to its metadata and a signed URL that needs no API key, so it is safe to hand to a browser and it expires within minutes.", "responses": { "200": { "description": "The file", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "file" }, "form_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "response_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size_bytes": { "type": "number" }, "created_at": { "type": "number" }, "download_url": { "type": "string" }, "download_expires_at": { "type": "number" } }, "required": [ "id", "object", "form_id", "response_id", "filename", "mime", "size_bytes", "created_at", "download_url", "download_expires_at" ] } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "file:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/files/{id}/content": { "get": { "operationId": "getV1FilesByIdContent", "tags": [ "v1" ], "summary": "A respondent's uploaded file, inline", "description": "The file's bytes in the JSON body under the same API key: UTF-8 text for text types, base64 otherwise. For a caller that cannot fetch `download_url`. Files over 4 MB answer 413; use `download_url` for those.", "responses": { "200": { "description": "The file's bytes", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "file_content" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "size_bytes": { "type": "number" }, "encoding": { "type": "string", "enum": [ "utf8", "base64" ] }, "data": { "type": "string" } }, "required": [ "id", "object", "filename", "mime", "size_bytes", "encoding", "data" ] } } } }, "404": { "description": "File not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Too large to return inline", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "file:read", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/uploads/intent": { "post": { "operationId": "postV1SessionsBySidUploadsIntent", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string" }, "filename": { "type": "string", "minLength": 1, "maxLength": 300 }, "mime": { "type": "string", "minLength": 3, "maxLength": 120 }, "size": { "type": "integer", "minimum": 1, "maximum": 104857600 } }, "required": [ "ref", "filename", "mime", "size" ] } } } }, "tags": [ "v1" ], "summary": "Register an upload, returning a fileId to PUT against", "responses": { "200": { "description": "Intent created", "content": { "application/json": { "schema": { "type": "object", "properties": { "fileId": { "type": "string" }, "uploadUrl": { "type": "string" } }, "required": [ "fileId", "uploadUrl" ] } } } }, "413": { "description": "Too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "415": { "description": "Unsupported type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "file:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/uploads/{fileId}": { "put": { "operationId": "putV1SessionsBySidUploadsByFileId", "tags": [ "v1" ], "summary": "Upload the bytes for a registered intent", "description": "PUT the raw file body, not multipart and not base64, to the `uploadUrl` returned by the intent step. The declared size must match within 1KB, and the object is not visible to the form until `confirm`.", "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "200": { "description": "Bytes stored", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Declared and actual size differ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "No such upload intent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "413": { "description": "Too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "fileId", "required": true } ], "x-required-scope": "file:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/uploads/{fileId}/confirm": { "post": { "operationId": "postV1SessionsBySidUploadsByFileIdConfirm", "tags": [ "v1" ], "summary": "Confirm an upload: flips pending to confirmed and notifies the session", "responses": { "200": { "description": "Confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } }, "400": { "description": "Not uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "fileId", "required": true } ], "x-required-scope": "file:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge": { "get": { "operationId": "getV1FormsByIdKnowledge", "tags": [ "v1" ], "summary": "List a form's knowledge sources", "responses": { "200": { "description": "Sources", "content": { "application/json": { "schema": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "title": { "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bytes": { "type": "number" }, "chunkCount": { "type": "number" }, "createdAt": { "type": "number" }, "indexedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mime": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "excerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "kind", "title", "origin", "status", "error", "bytes", "chunkCount", "createdAt", "indexedAt", "mime", "excerpt" ] } }, "usage": { "type": "object", "properties": { "bytes": { "type": "number" }, "maxBytes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "count": { "type": "number" }, "maxCount": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "bytes", "maxBytes", "count", "maxCount" ] }, "enabled": { "type": "boolean" } }, "required": [ "sources", "usage", "enabled" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge/text": { "post": { "operationId": "postV1FormsByIdKnowledgeText", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "body": { "type": "string", "minLength": 1, "maxLength": 500000 } }, "required": [ "title", "body" ] } } } }, "tags": [ "v1" ], "summary": "Add pasted text as knowledge", "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "402": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge/link": { "post": { "operationId": "postV1FormsByIdKnowledgeLink", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "title": { "type": "string", "maxLength": 200 } }, "required": [ "url" ] } } } }, "tags": [ "v1" ], "summary": "Add a web page as knowledge", "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "402": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge/crawl": { "post": { "operationId": "postV1FormsByIdKnowledgeCrawl", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "pages": { "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "url" ] } } } }, "tags": [ "v1" ], "summary": "Crawl a site and add its pages as knowledge", "responses": { "200": { "description": "Pages queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" } } }, "required": [ "ids" ] } } } }, "402": { "description": "Plan limit", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge/upload": { "post": { "operationId": "postV1FormsByIdKnowledgeUpload", "tags": [ "v1" ], "summary": "Upload a document, image or recording as knowledge", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "At most 25 MB." } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } } } }, "413": { "description": "Too large", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } }, "415": { "description": "Unsupported type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge/{sourceId}/file": { "get": { "operationId": "getV1FormsByIdKnowledgeBySourceIdFile", "tags": [ "v1" ], "summary": "Download an uploaded knowledge file", "description": "The file as it was uploaded. Images, PDFs and recordings are served inline so they can be previewed; anything else downloads.", "responses": { "200": { "description": "The file's bytes", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "No such file", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } }, "request_id": { "type": "string" }, "doc_url": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": {} } }, "required": [ "error" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "sourceId", "required": true } ], "x-required-scope": "form:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/knowledge/{sourceId}": { "delete": { "operationId": "deleteV1FormsByIdKnowledgeBySourceId", "tags": [ "v1" ], "summary": "Remove a knowledge source", "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ] } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "sourceId", "required": true } ], "x-required-scope": "form:write", "security": [ { "secretKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/sessions": { "post": { "operationId": "postV1FormsByIdSessions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "hiddenFields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_.-]{0,60}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "externalId": { "type": "string", "maxLength": 200 }, "expiresIn": { "type": "integer", "minimum": 300, "maximum": 2592000 }, "respondent": { "type": "object", "properties": { "country": { "type": "string", "maxLength": 8 }, "userAgent": { "type": "string", "maxLength": 300 } } } } } } } }, "tags": [ "v1" ], "summary": "Open a conversation on a published form", "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "respondentToken": { "type": "string" }, "expiresAt": { "type": "number" }, "streamUrl": { "type": "string" }, "greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "sessionId", "respondentToken", "expiresAt", "streamUrl", "greeting", "question" ] } } } }, "403": { "description": "The form is closed, capped, or over its response ceiling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "session:create", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/forms/{id}/chat/sessions": { "post": { "operationId": "postV1FormsByIdChatSessions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "default": {}, "type": "object", "properties": { "hiddenFields": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_.-]{0,60}$" }, "additionalProperties": { "type": "string", "maxLength": 500 } }, "externalId": { "type": "string", "maxLength": 200 }, "expiresIn": { "type": "integer", "minimum": 300, "maximum": 2592000 }, "respondent": { "type": "object", "properties": { "country": { "type": "string", "maxLength": 8 }, "userAgent": { "type": "string", "maxLength": 300 } } } } } } } }, "tags": [ "v1" ], "summary": "Open a conversation on a published form", "responses": { "200": { "description": "Session", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "respondentToken": { "type": "string" }, "expiresAt": { "type": "number" }, "streamUrl": { "type": "string" }, "greeting": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "sessionId", "respondentToken", "expiresAt", "streamUrl", "greeting", "question" ] } } } }, "403": { "description": "The form is closed, capped, or over its response ceiling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Form not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "x-required-scope": "session:create", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/sessions/{sid}/messages": { "post": { "operationId": "postV1SessionsBySidMessages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "structured" }, "ref": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,40}$" }, "value": {} }, "required": [ "type", "ref", "value" ] } ] } } } }, "tags": [ "v1" ], "summary": "Send a message or a structured answer, and get the turn's result", "parameters": [ { "name": "deadlineMs", "in": "query", "required": false, "schema": { "type": "number" }, "description": "How long to wait for the turn, in milliseconds, before answering 202 with what is done so far. Unparseable values are ignored." }, { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "responses": { "200": { "description": "The turn, with the next question", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq" ], "additionalProperties": {} } } } }, "202": { "description": "Still running; resume from `pollUrl`", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" }, "status": { "type": "string", "const": "processing" }, "pollUrl": { "type": "string" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq", "status", "pollUrl" ], "additionalProperties": {} } } } }, "400": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/actions": { "post": { "operationId": "postV1SessionsBySidActions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "skip", "stop", "restart", "edit", "submit", "resend_code", "change_answer", "undo_screen_out", "retry_payment", "cancel_payment", "simulate_payment" ] }, "ref": { "type": "string" } }, "required": [ "action" ] } } } }, "tags": [ "v1" ], "summary": "Skip, edit, restart, stop, submit, undo a screen-out, or resend a verification code", "parameters": [ { "name": "deadlineMs", "in": "query", "required": false, "schema": { "type": "number" }, "description": "How long to wait for the turn, in milliseconds, before answering 202 with what is done so far. Unparseable values are ignored." }, { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "responses": { "200": { "description": "The turn's result", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq" ], "additionalProperties": {} } } } }, "202": { "description": "Still running; resume from `pollUrl`", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" }, "status": { "type": "string", "const": "processing" }, "pollUrl": { "type": "string" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq", "status", "pollUrl" ], "additionalProperties": {} } } } }, "400": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}": { "get": { "operationId": "getV1SessionsBySid", "tags": [ "v1" ], "summary": "Session state", "responses": { "200": { "description": "State", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "status": { "type": "string" }, "currentRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "collected": { "type": "number" }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "summary": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "display": { "type": "string" } }, "required": [ "ref", "title", "display" ] } }, "awaitingSubmit": { "type": "boolean" }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "canRepeat": { "type": "boolean" }, "auth": { "anyOf": [ { "type": "object", "properties": { "method": { "type": "string" }, "message": { "type": "string" }, "verified": { "type": "boolean" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "method", "message", "verified", "label" ] }, { "type": "null" } ] }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "source": { "type": "string" } }, "required": [ "sessionId", "status", "currentRef", "collected", "answers", "variables", "summary", "awaitingSubmit", "completedAt", "ending", "canRepeat", "auth", "pendingVerification", "pendingPayment", "expiresAt", "mode", "source" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "session:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/events": { "get": { "operationId": "getV1SessionsBySidEvents", "tags": [ "v1" ], "summary": "The session's events, streamed or pulled since a sequence number", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Return a JSON page of events after this sequence number instead of a stream." }, { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "responses": { "200": { "description": "Server-sent events when `Accept: text/event-stream`, otherwise a JSON page of events since `since`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "latest_seq": { "type": "number" }, "has_more": { "type": "boolean" } }, "required": [ "events", "latest_seq", "has_more" ] } } } } }, "x-required-scope": "session:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/token/rotate": { "post": { "operationId": "postV1SessionsBySidTokenRotate", "tags": [ "v1" ], "summary": "Issue a fresh respondent token, invalidating the old one", "responses": { "200": { "description": "The new token", "content": { "application/json": { "schema": { "type": "object", "properties": { "respondentToken": { "type": "string" }, "rotatedAt": { "type": "number" } }, "required": [ "respondentToken", "rotatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/payments": { "post": { "operationId": "postV1SessionsBySidPayments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "phone": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "ref" ] } } } }, "tags": [ "v1" ], "summary": "Open a verified checkout for the current payment question", "responses": { "200": { "description": "Checkout opened, or the one already open", "content": { "application/json": { "schema": { "type": "object", "properties": { "recordId": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "recordId", "launch", "expiresAt" ] } } } }, "402": { "description": "The organization's plan does not include payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Not payable right now: `stale_ref`, `payment_unavailable`, `preview_live_account`, `live_account_in_test_mode` (a `*_test_` key on a live account), `already_paid`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`phone_required`: the gateway needs a number for the receipt — start again with `phone`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`too_many_attempts`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/payments/{recordId}/confirm": { "post": { "operationId": "postV1SessionsBySidPaymentsByRecordIdConfirm", "tags": [ "v1" ], "summary": "Re-check a checkout with the gateway, and settle it if it was paid", "responses": { "200": { "description": "Where the payment stands", "content": { "application/json": { "schema": { "type": "object", "properties": { "recordId": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "paid", "failed", "expired", "refunded", "superseded" ] }, "settled": { "type": "boolean" } }, "required": [ "recordId", "status", "settled" ] } } } }, "404": { "description": "No such payment on this session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The gateway could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "recordId", "required": true } ], "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/auth/google": { "post": { "operationId": "postV1SessionsBySidAuthGoogle", "tags": [ "v1" ], "summary": "Verify a respondent with a Google ID token", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "The token did not check out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This identity has already answered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8000 } }, "required": [ "idToken" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/auth/phone/token": { "post": { "operationId": "postV1SessionsBySidAuthPhoneToken", "tags": [ "v1" ], "summary": "Verify a respondent with a Firebase phone ID token", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "The token did not check out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This identity has already answered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8000 } }, "required": [ "idToken" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/auth/email/start": { "post": { "operationId": "postV1SessionsBySidAuthEmailStart", "tags": [ "v1" ], "summary": "Email a respondent a sign-in code", "responses": { "200": { "description": "Code sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "sentTo": { "type": "string" }, "devCode": { "type": "string" } }, "required": [ "ok", "sentTo" ] } } } }, "400": { "description": "Not an address, too many codes, or this form does not sign in by email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320 } }, "required": [ "email" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/auth/email/verify": { "post": { "operationId": "postV1SessionsBySidAuthEmailVerify", "tags": [ "v1" ], "summary": "Verify a respondent with the emailed sign-in code", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "Wrong, expired or used code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This identity has already answered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 4, "maxLength": 12 } }, "required": [ "code" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/sessions/{sid}/verify/phone-token": { "post": { "operationId": "postV1SessionsBySidVerifyPhoneToken", "tags": [ "v1" ], "summary": "Confirm a phone answer with a Firebase phone ID token", "responses": { "200": { "description": "The answer is verified and recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "The token did not check out, or proves a different number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8000 } }, "required": [ "idToken" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ] } }, "/v1/chat/sessions/{sid}/messages": { "post": { "operationId": "postV1ChatSessionsBySidMessages", "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "type": "string", "minLength": 1, "maxLength": 5000 } }, "required": [ "type", "text" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "structured" }, "ref": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,40}$" }, "value": {} }, "required": [ "type", "ref", "value" ] } ] } } } }, "tags": [ "v1" ], "summary": "Send a message or a structured answer, and get the turn's result", "parameters": [ { "name": "deadlineMs", "in": "query", "required": false, "schema": { "type": "number" }, "description": "How long to wait for the turn, in milliseconds, before answering 202 with what is done so far. Unparseable values are ignored." }, { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "responses": { "200": { "description": "The turn, with the next question", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq" ], "additionalProperties": {} } } } }, "202": { "description": "Still running; resume from `pollUrl`", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" }, "status": { "type": "string", "const": "processing" }, "pollUrl": { "type": "string" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq", "status", "pollUrl" ], "additionalProperties": {} } } } }, "400": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/actions": { "post": { "operationId": "postV1ChatSessionsBySidActions", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "skip", "stop", "restart", "edit", "submit", "resend_code", "change_answer", "undo_screen_out", "retry_payment", "cancel_payment", "simulate_payment" ] }, "ref": { "type": "string" } }, "required": [ "action" ] } } } }, "tags": [ "v1" ], "summary": "Skip, edit, restart, stop, submit, undo a screen-out, or resend a verification code", "parameters": [ { "name": "deadlineMs", "in": "query", "required": false, "schema": { "type": "number" }, "description": "How long to wait for the turn, in milliseconds, before answering 202 with what is done so far. Unparseable values are ignored." }, { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "responses": { "200": { "description": "The turn's result", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq" ], "additionalProperties": {} } } } }, "202": { "description": "Still running; resume from `pollUrl`", "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "type": "boolean" }, "complete": { "type": "boolean" }, "awaitingSubmit": { "type": "boolean" }, "assistantMessages": { "type": "array", "items": { "type": "string" } }, "question": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "ref": { "type": "string" }, "type": { "type": "string" }, "title": { "type": "string" }, "required": { "type": "boolean" }, "imageKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media": {} }, "required": [ "id", "ref", "type", "title", "required" ], "additionalProperties": {} }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "validation": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "ref", "code", "message" ] }, { "type": "null" } ] }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "collected": { "type": "number" }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "sinceSeq": { "type": "number" }, "status": { "type": "string", "const": "processing" }, "pollUrl": { "type": "string" } }, "required": [ "accepted", "complete", "awaitingSubmit", "assistantMessages", "question", "ending", "validation", "answers", "collected", "pendingVerification", "pendingPayment", "events", "sinceSeq", "status", "pollUrl" ], "additionalProperties": {} } } } }, "400": { "description": "Rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}": { "get": { "operationId": "getV1ChatSessionsBySid", "tags": [ "v1" ], "summary": "Session state", "responses": { "200": { "description": "State", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string" }, "status": { "type": "string" }, "currentRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "collected": { "type": "number" }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "variables": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "summary": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "display": { "type": "string" } }, "required": [ "ref", "title", "display" ] } }, "awaitingSubmit": { "type": "boolean" }, "completedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ending": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "title": { "type": "string" }, "bodyMd": { "type": "string" }, "kind": { "type": "string", "enum": [ "success", "screen_out" ] }, "requirements": { "type": "array", "items": { "type": "string" } } }, "required": [ "ref", "title" ], "additionalProperties": {} }, { "type": "null" } ] }, "canRepeat": { "type": "boolean" }, "auth": { "anyOf": [ { "type": "object", "properties": { "method": { "type": "string" }, "message": { "type": "string" }, "verified": { "type": "boolean" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "method", "message", "verified", "label" ] }, { "type": "null" } ] }, "pendingVerification": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "channel": { "type": "string", "enum": [ "sms", "email" ] }, "sentTo": { "type": "string" }, "sentAt": { "type": "number" } }, "required": [ "ref", "channel", "sentTo", "sentAt" ] }, { "type": "null" } ] }, "pendingPayment": { "anyOf": [ { "type": "object", "properties": { "ref": { "type": "string" }, "recordId": { "type": "string" }, "provider": { "type": "string", "enum": [ "cashfree", "razorpay", "stripe" ] }, "amountMinor": { "type": "number" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "display": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "ref", "recordId", "provider", "amountMinor", "amount", "currency", "display", "launch", "expiresAt" ] }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "source": { "type": "string" } }, "required": [ "sessionId", "status", "currentRef", "collected", "answers", "variables", "summary", "awaitingSubmit", "completedAt", "ending", "canRepeat", "auth", "pendingVerification", "pendingPayment", "expiresAt", "mode", "source" ], "additionalProperties": {} } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "session:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/events": { "get": { "operationId": "getV1ChatSessionsBySidEvents", "tags": [ "v1" ], "summary": "The session's events, streamed or pulled since a sequence number", "parameters": [ { "name": "since", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Return a JSON page of events after this sequence number instead of a stream." }, { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "responses": { "200": { "description": "Server-sent events when `Accept: text/event-stream`, otherwise a JSON page of events since `since`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "v": { "type": "number" }, "seq": { "type": "number" }, "ts": { "type": "number" }, "type": { "type": "string" }, "data": {} }, "required": [ "v", "seq", "ts", "type", "data" ] } }, "latest_seq": { "type": "number" }, "has_more": { "type": "boolean" } }, "required": [ "events", "latest_seq", "has_more" ] } } } } }, "x-required-scope": "session:read", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/token/rotate": { "post": { "operationId": "postV1ChatSessionsBySidTokenRotate", "tags": [ "v1" ], "summary": "Issue a fresh respondent token, invalidating the old one", "responses": { "200": { "description": "The new token", "content": { "application/json": { "schema": { "type": "object", "properties": { "respondentToken": { "type": "string" }, "rotatedAt": { "type": "number" } }, "required": [ "respondentToken", "rotatedAt" ] } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/payments": { "post": { "operationId": "postV1ChatSessionsBySidPayments", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ref": { "type": "string", "minLength": 1, "maxLength": 64 }, "phone": { "type": "string", "minLength": 1, "maxLength": 32 } }, "required": [ "ref" ] } } } }, "tags": [ "v1" ], "summary": "Open a verified checkout for the current payment question", "responses": { "200": { "description": "Checkout opened, or the one already open", "content": { "application/json": { "schema": { "type": "object", "properties": { "recordId": { "type": "string" }, "launch": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "cashfree_sdk" }, "orderId": { "type": "string" }, "paymentSessionId": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "kind", "orderId", "paymentSessionId", "mode" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "razorpay_checkout" }, "orderId": { "type": "string" }, "key": { "type": "string" }, "amountMinor": { "type": "number" }, "currency": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "prefill": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "contact": { "type": "string" } } } }, "required": [ "kind", "orderId", "key", "amountMinor", "currency", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "redirect" }, "url": { "type": "string" }, "sessionId": { "type": "string" } }, "required": [ "kind", "url", "sessionId" ] } ] }, "expiresAt": { "type": "number" } }, "required": [ "recordId", "launch", "expiresAt" ] } } } }, "402": { "description": "The organization's plan does not include payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Not payable right now: `stale_ref`, `payment_unavailable`, `preview_live_account`, `live_account_in_test_mode` (a `*_test_` key on a live account), `already_paid`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "`phone_required`: the gateway needs a number for the receipt — start again with `phone`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "`too_many_attempts`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/payments/{recordId}/confirm": { "post": { "operationId": "postV1ChatSessionsBySidPaymentsByRecordIdConfirm", "tags": [ "v1" ], "summary": "Re-check a checkout with the gateway, and settle it if it was paid", "responses": { "200": { "description": "Where the payment stands", "content": { "application/json": { "schema": { "type": "object", "properties": { "recordId": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "paid", "failed", "expired", "refunded", "superseded" ] }, "settled": { "type": "boolean" } }, "required": [ "recordId", "status", "settled" ] } } } }, "404": { "description": "No such payment on this session", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "502": { "description": "The gateway could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "recordId", "required": true } ], "x-required-scope": "session:write", "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/auth/google": { "post": { "operationId": "postV1ChatSessionsBySidAuthGoogle", "tags": [ "v1" ], "summary": "Verify a respondent with a Google ID token", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "The token did not check out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This identity has already answered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8000 } }, "required": [ "idToken" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/auth/phone/token": { "post": { "operationId": "postV1ChatSessionsBySidAuthPhoneToken", "tags": [ "v1" ], "summary": "Verify a respondent with a Firebase phone ID token", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "The token did not check out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This identity has already answered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8000 } }, "required": [ "idToken" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/auth/email/start": { "post": { "operationId": "postV1ChatSessionsBySidAuthEmailStart", "tags": [ "v1" ], "summary": "Email a respondent a sign-in code", "responses": { "200": { "description": "Code sent", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "sentTo": { "type": "string" }, "devCode": { "type": "string" } }, "required": [ "ok", "sentTo" ] } } } }, "400": { "description": "Not an address, too many codes, or this form does not sign in by email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "minLength": 3, "maxLength": 320 } }, "required": [ "email" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/auth/email/verify": { "post": { "operationId": "postV1ChatSessionsBySidAuthEmailVerify", "tags": [ "v1" ], "summary": "Verify a respondent with the emailed sign-in code", "responses": { "200": { "description": "Verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "Wrong, expired or used code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "This identity has already answered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 4, "maxLength": 12 } }, "required": [ "code" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/v1/chat/sessions/{sid}/verify/phone-token": { "post": { "operationId": "postV1ChatSessionsBySidVerifyPhoneToken", "tags": [ "v1" ], "summary": "Confirm a phone answer with a Firebase phone ID token", "responses": { "200": { "description": "The answer is verified and recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } }, "required": [ "ok" ], "additionalProperties": {} } } } }, "400": { "description": "The token did not check out, or proves a different number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "idToken": { "type": "string", "minLength": 10, "maxLength": 8000 } }, "required": [ "idToken" ] } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "sid", "required": true } ], "security": [ { "secretKey": [] }, { "publishableKey": [] }, { "apiKeyHeader": [] } ], "deprecated": true } }, "/d/{kind}/{id}": { "get": { "operationId": "getDByKindById", "tags": [ "public" ], "summary": "Follow a signed download link", "description": "You never build this URL yourself — `GET /v1/exports/{id}` and `GET /v1/files/{id}` return it complete. It carries no API key, expires within minutes, and answers 404 for anything it cannot serve, including a link that has expired.", "responses": { "200": { "description": "The bytes, as an attachment" }, "404": { "description": "Invalid, expired, or nothing to serve" } }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "kind", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ] } } } }