{ "openapi": "3.1.0", "info": { "title": "RouterClip API v1", "version": "1.0.0", "description": "Server-to-server API of RouterClip for a company's own systems (ERP, shop, backend). Authenticate with a key of an integration source: `Authorization: Bearer aio_.`; never put it in a browser, a tag manager or a URL. Every answer carries `X-Request-ID`. Errors are `{detail: {code, message, requestId, field?}}`. Guide: docs/API-V1.md.\n\nTask and function API (feature `api.tasks`): `If-Match` is required on every PATCH (428 without it, 412 when stale), `Idempotency-Key` on creations and on actions unless `dryRun`, and `X-AIO-Act-As` picks the delegated user. Catalog of kinds and actions: /developers/api-v1-task-kinds.json. Guide: docs/API-V1-TAREAS.md.\n\nAPI servidor a servidor de RouterClip para los sistemas de la empresa (ERP, tienda, backend). Autentica con una clave de una fuente de integración; nunca la pongas en un navegador, un gestor de etiquetas ni una URL. Cada respuesta lleva `X-Request-ID`. Guía: docs/API-V1.md; API de tareas y funciones: docs/API-V1-TAREAS.md." }, "tags": [ { "name": "Tasks", "description": "Unified task feed: list, detail, PATCH, creation, actions, notes, history, external links, kinds, change feed and summary. / Feed unificado de tareas: listado, detalle, PATCH, alta, acciones, notas, historial, enlaces externos, tipos, feed de cambios y resumen." }, { "name": "Contacts", "description": "Contacts, their notes and tasks, and double opt-in invitations. / Contactos, sus notas y tareas, e invitaciones de doble opt-in.", "x-aio-area": "contacts" }, { "name": "Companies", "description": "Customer companies, their contacts, notes and history. / Empresas cliente, sus contactos, notas e historial.", "x-aio-area": "companies" }, { "name": "Deals", "description": "Deals, pipelines (read only) and their actions. / Oportunidades, pipelines (lectura) y sus acciones.", "x-aio-area": "deals" }, { "name": "Activities", "description": "Activities and follow-ups. / Actividades y seguimientos.", "x-aio-area": "activities" }, { "name": "Sequences", "description": "Sales sequences, enrollments and mailbox status. / Secuencias comerciales, inscripciones y estado del buzón.", "x-aio-area": "sequences" }, { "name": "Playbooks", "description": "Sales playbooks and sessions. / Guiones comerciales y sesiones.", "x-aio-area": "playbooks" }, { "name": "Duplicates", "description": "Duplicate pairs, merges and undo. / Pares de duplicados, fusiones y deshacer.", "x-aio-area": "duplicates" }, { "name": "Support", "description": "Conversations, tickets and SLA, mentions, customer messages and team alerts, labels, macros and availability. / Conversaciones, tickets y SLA, menciones, recados y avisos al equipo, etiquetas, macros y disponibilidad.", "x-aio-area": "support" }, { "name": "CSAT", "description": "Satisfaction surveys and invitations. / Encuestas de satisfacción e invitaciones.", "x-aio-area": "csat" }, { "name": "Voice", "description": "Calls, voice jobs and capacity; never the audio. / Llamadas, trabajos de voz y capacidad; nunca el audio.", "x-aio-area": "voice" }, { "name": "Calendar", "description": "Calendars, availability and bookings. / Calendarios, disponibilidad y reservas.", "x-aio-area": "calendar" }, { "name": "Campaigns", "description": "Email, SMS and push campaigns, templates, delivery review and experiments. / Campañas de email, SMS y push, plantillas, revisión de entregas y experimentos.", "x-aio-area": "campaigns" }, { "name": "Journeys", "description": "Journeys, their enrollments, versions and contact scores. / Recorridos, sus inscripciones, versiones y puntuación de contactos.", "x-aio-area": "journeys" }, { "name": "Segments", "description": "Segments and their preview (counts only). / Segmentos y su vista previa (solo recuentos).", "x-aio-area": "segments" }, { "name": "Forms", "description": "Signup forms, web forms and placements. / Formularios de alta, formularios web y colocaciones.", "x-aio-area": "forms" }, { "name": "Sites", "description": "Verified websites and custom page domains. / Sitios web verificados y dominios propios de páginas.", "x-aio-area": "sites" }, { "name": "Conversions", "description": "Conversions and their reconciliation. / Conversiones y su conciliación.", "x-aio-area": "conversions" }, { "name": "Knowledge", "description": "Knowledge documents and storage. / Documentos de conocimiento y almacenamiento.", "x-aio-area": "knowledge" }, { "name": "Channels", "description": "Channels, marketing connections and mail domains. / Canales, conexiones de marketing y dominios de correo.", "x-aio-area": "channels" }, { "name": "Reports", "description": "Reports (read only, JSON). / Informes (solo lectura, JSON).", "x-aio-area": "reports" }, { "name": "Team", "description": "Members of the company (ID, name, role and, with team:emails, email). / Miembros de la empresa (ID, nombre, rol y, con team:emails, email).", "x-aio-area": "team" }, { "name": "Webhooks", "description": "Task webhooks of the key's source and failed marketing webhooks. / Webhooks de tareas de la fuente de la clave y webhooks de marketing fallidos.", "x-aio-area": "webhooks" }, { "name": "Automation", "description": "Automation flows without their configuration, their runs and starting the flows with the API trigger (TASKAPI-22). / Flujos de automatización sin su configuración, sus ejecuciones e inicio de los flujos con disparador API (TASKAPI-22).", "x-aio-area": "automation" }, { "name": "Key", "description": "The key, its source, scopes and capabilities. / La clave, su fuente, scopes y capacidades." }, { "name": "Events", "description": "Events and their receipts, historical import (API-02, V2-API-04), the event feed and its catalog (F4-c). / Eventos y sus recibos, importación histórica (API-02, V2-API-04), el feed de eventos y su catálogo (F4-c)." }, { "name": "Identity", "description": "Single-use tokens that link a customer's browser with their record (V2-IDENT-01). / Tokens de un solo uso para vincular el navegador de un cliente con su ficha (V2-IDENT-01)." } ], "security": [ { "aioApiKey": [] } ], "paths": { "/api/v1/activities": { "get": { "tags": [ "Activities" ], "summary": "List follow-ups", "description": "CRM follow-ups by due date with a cursor (scope `activities:read`); only IDs go in the URL.", "operationId": "listActivities", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "open (default), done, cancelled, overdue (open and due) or all.", "examples": [ "open" ], "title": "Status" }, "description": "open (default), done, cancelled, overdue (open and due) or all." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Follow-ups of this assignee (user ID).", "title": "Ownerid" }, "description": "Follow-ups of this assignee (user ID)." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked contact ID (never personal data in the URL).", "title": "Contactid" }, "description": "Linked contact ID (never personal data in the URL)." }, { "name": "dealId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked deal ID.", "title": "Dealid" }, "description": "Linked deal ID." }, { "name": "ticketId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked ticket ID.", "title": "Ticketid" }, "description": "Linked ticket ID." }, { "name": "activityKind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "task, call, email or meeting.", "examples": [ "call" ], "title": "Activitykind" }, "description": "task, call, email or meeting." }, { "name": "originType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "One origin: manual, sequence, playbook, api, assignment, journey, process, approval, scoring, sales_reply, assistant, quote, contract, meeting, flow (see originType).", "examples": [ "api" ], "title": "Origintype" }, "description": "One origin: manual, sequence, playbook, api, assignment, journey, process, approval, scoring, sales_reply, assistant, quote, contract, meeting, flow (see originType)." }, { "name": "dueBefore", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly before.", "title": "Duebefore" }, "description": "RFC 3339: due strictly before." }, { "name": "dueAfter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly after.", "title": "Dueafter" }, "description": "RFC 3339: due strictly after." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: changed at or after it.", "title": "Updatedsince" }, "description": "RFC 3339: changed at or after it." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Follow-ups of the company by due date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiActivityPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (activities:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Activities" ], "summary": "Create a follow-up", "description": "Create a follow-up through the same function as the UI (scope `activities:write`; `Idempotency-Key` required);\nthe same as `POST /api/v1/tasks` with `kind=crm.activity`. Optional `ticketId` and `externalLink`.", "operationId": "createActivity", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created through the same function as the UI (origin api; history with actor api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiActivity" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the follow-up; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new follow-up (/api/v1/activities/{id}).", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (activities:write), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND, DEAL_NOT_FOUND or TICKET_NOT_FOUND (another company's record answers the same).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN, MERGED_RECORD (canonicalId: link the kept contact), DEAL_ARCHIVED or TICKET_MERGED (canonicalId: the ticket it was merged into) or EXTERNAL_ID_TAKEN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), ASSIGNEE_INVALID, LINKS_MISMATCH, ACTIVITY_CHANGE_VETOED or another code of a guard of the follow-up (guard, field): APPROVAL_DECISION_REQUIRED (the task of a pending approval is decided in the app), PROCESS_TASK_LINKED (a process task keeps its deal) or SEQUENCE_TASK_LINKED (a sequence task keeps its contact and deal); EXTERNAL_LINK_URL_INVALID or EXTERNAL_ID_* for externalLink.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title", "dueAt" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "activityKind": { "type": "string", "enum": [ "task", "call", "email", "meeting" ], "default": "task" }, "dueAt": { "type": "string", "format": "date-time" }, "priority": { "type": "string", "enum": [ "normal", "high" ], "default": "normal" }, "description": { "type": "string", "maxLength": 10000 }, "assigneeId": { "type": [ "string", "null" ], "maxLength": 64, "description": "By default the delegated user, or nobody; null: unassigned." }, "contactId": { "type": [ "string", "null" ], "maxLength": 64 }, "dealId": { "type": [ "string", "null" ], "maxLength": 64 }, "ticketId": { "type": [ "string", "null" ], "maxLength": 64, "description": "A ticket that was not merged." }, "externalLink": { "type": "object", "additionalProperties": false, "required": [ "externalId", "url" ], "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your ID (never an email or a phone)." }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS, without credentials." } } } } }, "examples": { "ticket": { "summary": "A follow-up of a ticket from the tool", "value": { "title": "Llamar para confirmar la solución", "activityKind": "call", "dueAt": "2026-10-02T09:00:00Z", "priority": "high", "ticketId": "9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "externalLink": { "externalId": "PROJ-88", "url": "https://tool.example.com/browse/PROJ-88" } } } } } } } } }, "/api/v1/activities/{activity_id}": { "get": { "tags": [ "Activities" ], "summary": "Read a follow-up", "description": "A follow-up with its `ETag` (scope `activities:read`).", "operationId": "getActivity", "parameters": [ { "name": "activity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Activity Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The follow-up with its ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiActivity" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the follow-up; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (activities:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "ACTIVITY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Activities" ], "summary": "Update a follow-up", "description": "Change a follow-up with one internal call (scope `activities:write`, `activities:execute` for the status) and\noptimistic concurrency (`If-Match`).", "operationId": "updateActivity", "parameters": [ { "name": "activity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Activity Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The follow-up after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiActivity" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the follow-up; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (activities:write; activities:execute to change the status), FEATURE_DISABLED or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "ACTIVITY_NOT_FOUND, CONTACT_NOT_FOUND, DEAL_NOT_FOUND or TICKET_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN, MERGED_RECORD (canonicalId: link the kept contact), DEAL_ARCHIVED or TICKET_MERGED (canonicalId: the ticket it was merged into).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"\" of the follow-up; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), ASSIGNEE_INVALID, LINKS_MISMATCH, ACTIVITY_CHANGE_VETOED or another code of a guard of the follow-up (guard, field): APPROVAL_DECISION_REQUIRED (the task of a pending approval is decided in the app), PROCESS_TASK_LINKED (a process task keeps its deal) or SEQUENCE_TASK_LINKED (a sequence task keeps its contact and deal), TASK_STATUS_REQUIRES_ACTION or IF_MATCH_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only the fields sent change, with one internal call. A status change also needs activities:execute. Send If-Match with the ETag you read.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 5000 }, "activityKind": { "type": "string", "enum": [ "task", "call", "email", "meeting" ] }, "status": { "type": "string", "enum": [ "open", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "normal", "high" ] }, "dueAt": { "type": "string", "format": "date-time" }, "assigneeId": { "type": [ "string", "null" ], "maxLength": 64, "description": "null removes the assignee." }, "contactId": { "type": [ "string", "null" ], "maxLength": 64 }, "dealId": { "type": [ "string", "null" ], "maxLength": 64 }, "ticketId": { "type": [ "string", "null" ], "maxLength": 64, "description": "null removes the link." } } }, "examples": { "postpone": { "summary": "Reassign and postpone", "value": { "assigneeId": "3c1f2a9e-0000-4000-8000-000000000000", "dueAt": "2026-10-03T09:00:00Z" } } } } } } } }, "/api/v1/activities/{activity_id}/history": { "get": { "tags": [ "Activities" ], "summary": "Read the history of a follow-up", "description": "Date, type, actor and changed fields of the follow-up's history, without values (scope `activities:read`).", "operationId": "getActivityHistory", "parameters": [ { "name": "activity_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Activity Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Changes of the follow-up: date, type, actor (user, api or system) and changed fields; never values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiActivityHistory" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (activities:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "ACTIVITY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (limit 1-100).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/activities/{resource_id}/actions/{action}": { "post": { "tags": [ "Activities" ], "summary": "Run an action of a follow-up", "description": "Run an action of a activities resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runActivityAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function; ACTIVITY_CHANGE_VETOED or another code of a guard of the follow-up (guard, field): APPROVAL_DECISION_REQUIRED (the task of a pending approval is decided in the app), PROCESS_TASK_LINKED or SEQUENCE_TASK_LINKED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "cancel": { "summary": "Cancel (crm_activity.cancel; activities:execute, service)", "value": { "input": {} } }, "complete": { "summary": "Complete (crm_activity.complete; activities:execute, service)", "value": { "input": {} } }, "reassign": { "summary": "Reassign (crm_activity.reassign; activities:execute, service)", "value": { "input": { "assigneeId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "reopen": { "summary": "Reopen (crm_activity.reopen; activities:execute, service)", "value": { "input": {} } }, "reschedule": { "summary": "Reschedule (crm_activity.reschedule; activities:execute, service)", "value": { "input": { "dueAt": "2026-10-01T09:00:00Z" } } }, "start_playbook": { "summary": "Start a playbook (crm_activity.start_playbook; activities:read, delegated)", "value": { "input": { "playbookId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } } } } } } } }, "/api/v1/automation/flows": { "get": { "tags": [ "Automation" ], "summary": "List automation flows", "description": "Flows with their status, trigger type and the version in use; never their definition (scope `automation:read`,\nfeature `automation.flows`).", "operationId": "listAutomationFlows", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated flow statuses (draft, active, paused, archived); every one but archived by default.", "examples": [ "active" ], "title": "Status" }, "description": "Comma separated flow statuses (draft, active, paused, archived); every one but archived by default." }, { "name": "subjectType", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated subject types (contact, deal, conversation).", "examples": [ "contact" ], "title": "Subjecttype" }, "description": "Comma separated subject types (contact, deal, conversation)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Flows of the company, newest first, without their definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAutomationFlowPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired (24 h) or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (automation:read) or FEATURE_DISABLED (api.tasks or automation.flows).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automation/flows/{flow_id}": { "get": { "tags": [ "Automation" ], "summary": "Read an automation flow", "description": "A flow without its definition (scope `automation:read`).", "operationId": "getAutomationFlow", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The flow without its definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAutomationFlow" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (automation:read) or FEATURE_DISABLED (api.tasks or automation.flows).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "FLOW_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automation/flows/{flow_id}/enroll": { "post": { "tags": [ "Automation" ], "summary": "Start a flow for a subject", "description": "Start a flow with the API trigger for a contact, deal or conversation (scope `automation:enroll`). Decided in the\nrequest by the flow's entry checks: 201 started or 200 skipped with the reason. Never writes to the customer.", "operationId": "enrollInAutomationFlow", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow Id" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "A run started now by the flow's entry checks (result started).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAutomationEnrollResult" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "200": { "description": "No run (result skipped) with its reason; a retry with the same Idempotency-Key gives the same answer.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAutomationEnrollResult" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (automation:enroll) or FEATURE_DISABLED (api.tasks or automation.flows).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "FLOW_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "FLOW_NOT_PUBLISHED, FLOW_TRIGGER_NOT_API, IDEMPOTENCY_CONFLICT (same key, another body) or IDEMPOTENCY_IN_PROGRESS.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "VALIDATION_ERROR or FIELD_NOT_ALLOWED (field), SUBJECT_TYPE_MISMATCH or IDEMPOTENCY_KEY_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED: send an Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject" ], "properties": { "subject": { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "contact", "deal", "conversation" ], "description": "The subject type of the flow." }, "id": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$", "description": "RouterClip ID of the contact (a merged ID starts the kept contact), deal or conversation." } } } } }, "examples": { "contact": { "summary": "Start a contact flow for a customer of your shop", "value": { "subject": { "type": "contact", "id": "3f1d2c4b0a9e4c7d8b6a5e4f3d2c1b0a" } } }, "deal": { "summary": "Start a deal flow", "value": { "subject": { "type": "deal", "id": "9a8b7c6d5e4f4a3b2c1d0e9f8a7b6c5d" } } } } } } } } }, "/api/v1/automation/flows/{flow_id}/runs": { "get": { "tags": [ "Automation" ], "summary": "List the runs of a flow", "description": "Runs newest first with their status, step and codes (scope `automation:read`).", "operationId": "listAutomationFlowRuns", "parameters": [ { "name": "flow_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Flow Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated run statuses (active, waiting, processing, paused, completed, exited, failed, cancelled).", "examples": [ "failed,paused" ], "title": "Status" }, "description": "Comma separated run statuses (active, waiting, processing, paused, completed, exited, failed, cancelled)." }, { "name": "subjectId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Runs of this contact, deal or conversation ID.", "title": "Subjectid" }, "description": "Runs of this contact, deal or conversation ID." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Runs of the flow, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAutomationRunPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired (24 h) or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (automation:read) or FEATURE_DISABLED (api.tasks or automation.flows).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "FLOW_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automation/runs/{run_id}": { "get": { "tags": [ "Automation" ], "summary": "Read a flow run", "description": "A run step by step: type, status, result code and the record each step created (scope `automation:read`).", "operationId": "getAutomationRun", "parameters": [ { "name": "run_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Run Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The run with its steps (type, status, result code and effect).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiAutomationRun" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (automation:read) or FEATURE_DISABLED (api.tasks or automation.flows).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "FLOW_RUN_NOT_FOUND: it does not exist or belongs to another company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automations": { "get": { "tags": [ "Journeys" ], "summary": "List the journeys of the source", "description": "The journeys your source allows (scope `automations:enroll`), with whether each one accepts enrollments now; with\n`journeys:read` (feature `api.tasks`), every journey of the company with its attention task and ETag.", "operationId": "listAutomations", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only with journeys:read: comma separated statuses (draft, active, paused, cancelled).", "examples": [ "active" ], "title": "Status" }, "description": "Only with journeys:read: comma separated statuses (draft, active, paused, cancelled)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only with journeys:read: 1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "Only with journeys:read: 1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only with journeys:read: nextCursor of the previous page.", "title": "Cursor" }, "description": "Only with journeys:read: nextCursor of the previous page." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The journeys of the source's allowed list (automations:enroll with marketing.api) or of the company (journeys:read with api.tasks; otherwise 403 FEATURE_DISABLED api.tasks, 400 CURSOR_INVALID and 422 for a bad query).", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "id", "name", "status", "trigger", "enrollable" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "cancelled" ] }, "trigger": { "type": "string", "enum": [ "manual", "segment", "event", "date", "api" ] }, "enrollable": { "type": "boolean", "description": "Active and with the API trigger: POST …/enroll can enroll into it." } } } }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Only with journeys:read: opaque cursor of the next page." }, "hasMore": { "type": "boolean", "description": "Only with journeys:read." } }, "description": "With automations:enroll only: the journeys of the source's allowed list. With journeys:read (api.tasks): every journey of the company as ApiJourney (GET /api/v1/automations/{id}), newest first, with nextCursor and hasMore." } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (journeys:read or automations:enroll) or FEATURE_DISABLED: the allowed list of automations:enroll needs marketing.api (feature marketing.api) and the company list of journeys:read needs api.tasks (feature api.tasks).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/automations/{automation_id}": { "get": { "tags": [ "Journeys" ], "summary": "Read a journey", "description": "A journey with its definition, counts, attention task, actions and `ETag` (scope `journeys:read`).", "operationId": "getAutomation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Automation Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The journey with its definition, counts, attention task, actions and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiJourney" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the journey; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (journeys:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "JOURNEY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automations/{automation_id}/actions/{action}": { "post": { "tags": [ "Journeys" ], "summary": "Run an action of a journey", "description": "activate, pause, resume, cancel or retry_sends (and resume_enrollment, cancel_enrollment, resume_automation of its\nattention task): `journeys:admin` with a delegated administrator; the same checks, `dryRun` and idempotency as the\ntask actions.", "operationId": "runAutomationAction", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Automation Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "activate": { "summary": "Activate (journey.activate; journeys:admin, delegated)", "value": { "input": {} } }, "cancel": { "summary": "Cancel (journey.cancel; journeys:admin, delegated)", "value": { "input": {} } }, "pause": { "summary": "Pause (journey.pause; journeys:admin, delegated)", "value": { "input": {} } }, "resume": { "summary": "Resume (journey.resume; journeys:admin, delegated)", "value": { "input": {} } }, "retry_sends": { "summary": "Retry paused sends (journey.retry_sends; journeys:admin, delegated)", "value": { "input": {} } }, "cancel_enrollment": { "summary": "Cancel an enrollment (journey_attention.cancel_enrollment; journeys:admin, delegated)", "value": { "input": { "enrollmentId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "resume_automation": { "summary": "Resume the journey (journey_attention.resume_automation; journeys:admin, delegated)", "value": { "input": {} } }, "retry": { "summary": "Retry the sends the delivery worker paused", "value": { "input": {} } }, "resume_enrollment": { "summary": "Resume a failed enrollment", "value": { "input": { "enrollmentId": "e-1" } } } } } } } } }, "/api/v1/automations/{automation_id}/enroll": { "post": { "tags": [ "Journeys" ], "summary": "Enroll a contact into a journey", "description": "Enroll a contact your source reaches into an allowed journey with the API trigger (scope\n`automations:enroll`). Decided in the request by the journey's entry policy: 201 enrolled or 200 skipped with\nthe reason. Never grants consents or sends anything by itself.", "operationId": "enrollInAutomation", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Automation Id" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (422 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Enrolled now by the journey's entry policy (result enrolled). Not delivered: send steps apply every permission and suppression check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "automationId" ], "properties": { "result": { "type": "string", "enum": [ "enrolled", "skipped" ], "description": "enrolled is not delivered." }, "enrollmentId": { "type": "string", "description": "Only with result enrolled." }, "reason": { "type": "string", "enum": [ "alreadyEnrolled", "activeEnrollmentExists", "cooldown", "entryLimitReached", "automationNotActive", "subjectUnavailable" ], "description": "Only with result skipped." }, "automationId": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "200": { "description": "Not enrolled (result skipped) with reason alreadyEnrolled, activeEnrollmentExists, cooldown, entryLimitReached, automationNotActive or subjectUnavailable. A retry with the same Idempotency-Key gives the same answer.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "result", "automationId" ], "properties": { "result": { "type": "string", "enum": [ "enrolled", "skipped" ], "description": "enrolled is not delivered." }, "enrollmentId": { "type": "string", "description": "Only with result enrolled." }, "reason": { "type": "string", "enum": [ "alreadyEnrolled", "activeEnrollmentExists", "cooldown", "entryLimitReached", "automationNotActive", "subjectUnavailable" ], "description": "Only with result skipped." }, "automationId": { "type": "string" } } } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (automations:enroll) or FEATURE_DISABLED (marketing.api).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "AUTOMATION_NOT_FOUND: not a journey of the source's allowed list.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "409": { "description": "AUTOMATION_TRIGGER_NOT_API, IDEMPOTENCY_CONFLICT (same key, another body), IDEMPOTENCY_IN_PROGRESS or SUBJECT_IDENTITY_CONFLICT.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, ENROLL_BODY_INVALID, ENROLL_FIELD_UNKNOWN, SUBJECT_REQUIRED, SUBJECT_INVALID, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE or REASON_EVENT_INVALID (not an event of this source, company and contact).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject" ], "properties": { "subject": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "contactId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "RouterClip contact ID the source reaches (a merged ID resolves to the kept one)." }, "externalId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your customer ID linked to a contact in this source; never an email or phone." } }, "description": "At least one identity; both must identify the same contact." }, "reasonEventId": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "Optional: the id of an event receipt of this source and contact, kept as the cause of the entry. Not your eventId." } } }, "examples": { "byExternalId": { "summary": "Enroll your customer after a declared purchase", "value": { "subject": { "externalId": "customer_872" }, "reasonEventId": "5f2c9e0b7d8a4c1e9b3f6a2d4e8c1b7a" } }, "byContactId": { "summary": "Enroll a contact by its RouterClip ID", "value": { "subject": { "contactId": "3f1d2c4b-0a9e-4c7d-8b6a-5e4f3d2c1b0a" } } } } } } } } }, "/api/v1/automations/{automation_id}/enrollments": { "get": { "tags": [ "Journeys" ], "summary": "List the enrollments of a journey", "description": "Enrollments with their step, errors and actions; the contact with only the source's read fields (scope\n`journeys:read`).", "operationId": "listAutomationEnrollments", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Automation Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated enrollment statuses (active, waiting, paused, completed, cancelled, failed).", "examples": [ "failed,paused" ], "title": "Status" }, "description": "Comma separated enrollment statuses (active, waiting, paused, completed, cancelled, failed)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Enrollments of the journey, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiJourneyEnrollmentPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (journeys:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "JOURNEY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automations/{automation_id}/versions": { "get": { "tags": [ "Journeys" ], "summary": "List the versions of a journey", "description": "The published versions of a journey with their differences, the summary of its draft and the task\n`marketing.journey_version` (scope `journeys:read`).", "operationId": "listAutomationVersions", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Automation Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The versions of the journey, the draft summary, the task and the journey's ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiJourneyVersions" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the journey; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (journeys:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "JOURNEY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/automations/{automation_id}/versions/actions/{action}": { "post": { "tags": [ "Journeys" ], "summary": "Run an action of the versions of a journey", "description": "publish_version (`journeys:admin`, delegated administrator): `dryRun` validates and answers the differences and the\n`draftRevision` to confirm; the execution needs it (409 when the draft changed).", "operationId": "runAutomationVersionAction", "parameters": [ { "name": "automation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Automation Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "publish_version": { "summary": "Publish version (journey_version.publish_version; journeys:admin, delegated)", "value": { "input": { "draftRevision": 3 } } }, "publish_version.dryRun": { "summary": "Publish version: dryRun returns the confirmation token(s) draftRevision", "value": { "dryRun": true, "input": {} } }, "review": { "summary": "dryRun: validation and differences, and the draftRevision to confirm", "value": { "dryRun": true, "input": {} } }, "publish": { "summary": "Publish the draft you reviewed (409 when it changed)", "value": { "input": { "draftRevision": 4 } } } } } } } } }, "/api/v1/bookings": { "get": { "tags": [ "Calendar" ], "summary": "List bookings", "description": "Bookings of the company calendars, unconfirmed first, with their task (scope `calendar:read`).", "operationId": "listBookings", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated statuses: pending, requesting, confirmed, cancelled, superseded or expired.", "examples": [ "requesting" ], "title": "Status" }, "description": "Comma separated statuses: pending, requesting, confirmed, cancelled, superseded or expired." }, { "name": "calendarId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The bookings of this calendar.", "title": "Calendarid" }, "description": "The bookings of this calendar." }, { "name": "history", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: also replaced and expired proposals.", "examples": [ "false" ], "title": "History" }, "description": "true: also replaced and expired proposals." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Bookings: unconfirmed first, then newest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiBookingPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (calendar:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/bookings/{resource_id}/actions/{action}": { "post": { "tags": [ "Calendar" ], "summary": "Run an action of a booking", "description": "Run an action of a bookings resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runBookingAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "reconcile": { "summary": "Check with the calendar (calendar_booking.reconcile; calendar:execute, service)", "value": { "input": {} } } } } } } } }, "/api/v1/calendars": { "get": { "tags": [ "Calendar" ], "summary": "List calendars", "description": "Company calendars with their schedule settings (scope `calendar:read`).", "operationId": "listCalendars", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Company calendars (archived ones left out).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCalendarPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (calendar:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/calendars/{calendar_id}/availability": { "get": { "tags": [ "Calendar" ], "summary": "Read the availability of a calendar", "description": "Free slots between `from` and `to` (at most 14 days; scope `calendar:read`).", "operationId": "getCalendarAvailability", "parameters": [ { "name": "calendar_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Calendar Id" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required: RFC 3339 with its offset, within the next 90 days.", "examples": [ "2026-10-07T00:00:00Z" ], "title": "From" }, "description": "Required: RFC 3339 with its offset, within the next 90 days." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 with its offset; 3 days after from by default and at most 14 days after it.", "examples": [ "2026-10-10T00:00:00Z" ], "title": "To" }, "description": "RFC 3339 with its offset; 3 days after from by default and at most 14 days after it." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Free slots between from and to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCalendarAvailability" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (calendar:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CALENDAR_NOT_FOUND: it does not exist, is paused or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "CALENDAR_RECONNECT_REQUIRED: authorize the calendar account again in the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "VALIDATION_ERROR (from is required; to after from), AVAILABILITY_RANGE_TOO_LARGE (more than 14 days or too many events), AVAILABILITY_RANGE_INVALID (not within the next 90 days) or QUERY_PARAMETER_NOT_ALLOWED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "502": { "description": "PROVIDER_ERROR: the calendar provider did not answer; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/campaign-recipients/{resource_id}/actions/{action}": { "post": { "tags": [ "Campaigns" ], "summary": "Review a campaign send", "description": "Run an action of a campaign-recipients resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runCampaignRecipientAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "review": { "summary": "Review the send (campaign_recipient.review; campaigns:admin, delegated)", "value": { "input": { "decision": "retry", "confirmPossibleDuplicate": true } } } } } } } } }, "/api/v1/campaigns": { "get": { "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "Email, SMS and push campaigns, newest first, with their task, A/B state and actions (scope `campaigns:read`).", "operationId": "listCampaigns", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated campaign statuses (draft, scheduled, running, paused, completed, cancelled).", "examples": [ "draft,paused" ], "title": "Status" }, "description": "Comma separated campaign statuses (draft, scheduled, running, paused, completed, cancelled)." }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "email, sms or push (push needs marketing.push).", "examples": [ "email" ], "title": "Channel" }, "description": "email, sms or push (push needs marketing.push)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Campaigns, newest first (without journey sends and subscription confirmations; push ones only with marketing.push).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCampaignPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:read) or FEATURE_DISABLED (api.tasks, or marketing.push for a push campaign).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Campaigns" ], "summary": "Create a campaign draft", "description": "Create a draft through the same function as the app (scope `campaigns:write`; `Idempotency-Key` required). A push\ndraft needs `marketing.push`.", "operationId": "createCampaign", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "The new draft, created through the same function as the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCampaign" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the campaign; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new campaign.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:write), FEATURE_DISABLED (api.tasks, marketing.push for push) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "MARKETING_RECORD_NOT_FOUND or CONNECTION_NOT_FOUND: a segment or connection of another company or missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS, ACTION_OUTCOME_UNKNOWN or a code of the app (CONNECTION_RETIRED…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), PUSH_* or a code of the app (CONNECTION_CHANNEL_MISMATCH…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "channel", "body" ], "description": "The fields of the campaign editor of the app; the campaign is always created as a draft.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "email", "sms", "push" ] }, "connectionId": { "type": [ "string", "null" ] }, "purpose": { "type": "string" }, "subject": { "type": "string", "maxLength": 500 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 }, "filters": { "type": [ "object", "null" ] }, "segmentId": { "type": [ "string", "null" ] }, "content": { "type": [ "object", "null" ] }, "trackOpens": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "utm": { "type": [ "object", "null" ] }, "abTest": { "type": [ "object", "null" ] }, "push": { "type": [ "object", "null" ], "description": "Push only (marketing.push): targetUrl, iconUrl, audience, ttlMinutes, trackClicks." }, "experiment": { "type": [ "object", "null" ] } } }, "examples": { "email": { "summary": "An email draft for a segment", "value": { "name": "Novedades de octubre", "channel": "email", "connectionId": "c0de…", "subject": "Hola {{name}}", "body": "Te contamos las novedades de este mes.", "segmentId": "5e9a…" } } } } } } } }, "/api/v1/campaigns/{campaign_id}": { "get": { "tags": [ "Campaigns" ], "summary": "Read a campaign", "description": "A campaign with its A/B test, tasks, actions and `ETag` (scope `campaigns:read`); never its recipients.", "operationId": "getCampaign", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The campaign with its A/B state, tasks, actions and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCampaign" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the campaign; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:read) or FEATURE_DISABLED (api.tasks, or marketing.push for a push campaign).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CAMPAIGN_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "patch": { "tags": [ "Campaigns" ], "summary": "Update a campaign draft", "description": "Change a draft through the same function as the app (scope `campaigns:write`; `If-Match` required).", "operationId": "updateCampaign", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The draft after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCampaign" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the campaign; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:write) or FEATURE_DISABLED (api.tasks, marketing.push).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CAMPAIGN_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "CAMPAIGN_NOT_DRAFT, CAMPAIGN_TEST_PENDING, CAMPAIGN_JOURNEY_TEMPLATE, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"h:<16 hex>\" of the campaign; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), IF_MATCH_INVALID, PUSH_* or a code of the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only drafts; send If-Match with the ETag you read.", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "channel": { "type": "string", "enum": [ "email", "sms", "push" ] }, "connectionId": { "type": [ "string", "null" ] }, "purpose": { "type": "string" }, "subject": { "type": "string", "maxLength": 500 }, "body": { "type": "string", "minLength": 1, "maxLength": 50000 }, "filters": { "type": [ "object", "null" ] }, "segmentId": { "type": [ "string", "null" ] }, "content": { "type": [ "object", "null" ] }, "trackOpens": { "type": "boolean" }, "trackClicks": { "type": "boolean" }, "utm": { "type": [ "object", "null" ] }, "abTest": { "type": [ "object", "null" ] }, "push": { "type": [ "object", "null" ], "description": "Push only (marketing.push): targetUrl, iconUrl, audience, ttlMinutes, trackClicks." }, "experiment": { "type": [ "object", "null" ] } } }, "examples": { "rename": { "summary": "Rename the draft", "value": { "name": "Novedades de noviembre" } } } } } } } }, "/api/v1/campaigns/{campaign_id}/actions/{action}": { "post": { "tags": [ "Campaigns" ], "summary": "Run an action of a campaign", "description": "preview, schedule (dryRun = preview; `audienceFingerprint`), pause, resume, cancel, clone, review_recipient or\ndecide: the same checks, `dryRun` and idempotency as the task actions.", "operationId": "runCampaignAction", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "review_recipient": { "summary": "Review a send (campaign_delivery.review_recipient; campaigns:admin, delegated)", "value": { "input": { "recipientId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "decision": "retry", "confirmPossibleDuplicate": true } } }, "cancel": { "summary": "Cancel (marketing_campaign.cancel; campaigns:admin, delegated)", "value": { "input": {} } }, "clone": { "summary": "Clone (marketing_campaign.clone; campaigns:write, delegated)", "value": { "input": {} } }, "pause": { "summary": "Pause (marketing_campaign.pause; campaigns:admin, delegated)", "value": { "input": {} } }, "preview.example": { "summary": "Review the audience (marketing_campaign.preview; campaigns:write, service)", "value": { "input": {} } }, "preview.dryRun": { "summary": "Review the audience: dryRun returns the confirmation token(s)", "value": { "dryRun": true, "input": {} } }, "resume": { "summary": "Resume (marketing_campaign.resume; campaigns:admin, delegated)", "value": { "input": {} } }, "schedule.dryRun": { "summary": "Schedule: dryRun returns the confirmation token(s) audienceFingerprint", "value": { "dryRun": true, "input": { "sendAt": "2026-10-01T08:00:00Z" } } }, "preview": { "summary": "Two steps, 1: the dryRun of schedule returns the audienceFingerprint", "value": { "dryRun": true, "input": {} } }, "schedule": { "summary": "Two steps, 2: schedule with the token (409 AUDIENCE_CHANGED if the audience changed)", "value": { "input": { "audienceFingerprint": "9ab3000000000000000000000000000000000000000000000000000000000000", "sendAt": "2026-10-02T09:00:00Z" } } }, "review": { "summary": "Retry an uncertain send", "value": { "input": { "recipientId": "r-1", "decision": "retry", "confirmPossibleDuplicate": true } } }, "decide": { "summary": "Release variant B to the rest", "value": { "input": { "decision": "release", "variantId": "b", "reason": "B wins clearly" } } } } } } } } }, "/api/v1/campaigns/{campaign_id}/analytics": { "get": { "tags": [ "Campaigns" ], "summary": "Read the results of a campaign", "description": "Aggregated results, links and the A/B report (scope `campaigns:read`).", "operationId": "getCampaignAnalytics", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Aggregated results of the campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCampaignAnalytics" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:read) or FEATURE_DISABLED (api.tasks, or marketing.push for a push campaign).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CAMPAIGN_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/campaigns/{campaign_id}/recipients": { "get": { "tags": [ "Campaigns" ], "summary": "List the recipients of a campaign", "description": "Real recipients without subject or body (scope `campaigns:read`); the address only when the source reads emails or\nphones.", "operationId": "listCampaignRecipients", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated recipient statuses (queued, sending, accepted, delivered, failed, uncertain, suppressed, cancelled).", "examples": [ "uncertain,failed" ], "title": "Status" }, "description": "Comma separated recipient statuses (queued, sending, accepted, delivered, failed, uncertain, suppressed, cancelled)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Real recipients of the campaign without content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCampaignRecipientPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:read) or FEATURE_DISABLED (api.tasks, or marketing.push for a push campaign).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CAMPAIGN_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/channels": { "get": { "tags": [ "Channels" ], "summary": "List channels", "description": "Channel accounts with their health and task (scope `channels:read`); never configuration or credentials.", "operationId": "listChannels", "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "whatsapp, email, social, voice, web or web_form.", "examples": [ "email" ], "title": "Type" }, "description": "whatsapp, email, social, voice, web or web_form." }, { "name": "provider", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "whatsapp, waha, gmail, microsoft, imap, messenger, instagram, twilio, widget or web_form.", "examples": [ "gmail" ], "title": "Provider" }, "description": "whatsapp, waha, gmail, microsoft, imap, messenger, instagram, twilio, widget or web_form." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Channel accounts of the company, oldest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiChannelPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (channels:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/channels/{channel_id}": { "get": { "tags": [ "Channels" ], "summary": "Read a channel", "description": "A channel account with its activity, setup and `ETag` (scope `channels:read`).", "operationId": "getChannel", "parameters": [ { "name": "channel_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Channel Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "The channel with its activity and setup; never its configuration or credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiChannel" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (channels:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CHANNEL_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/channels/{resource_id}/actions/{action}": { "post": { "tags": [ "Channels" ], "summary": "Run an action of a channel", "description": "Run an action of a channels resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runChannelAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "verify": { "summary": "Verify with the provider (channel_account.verify; channels:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/companies": { "get": { "tags": [ "Companies" ], "summary": "List customer companies", "description": "Customer companies by cursor (scope `companies:read`); filters `ids`, `updatedSince` and `status`.", "operationId": "listCompanies", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated record IDs (up to 100); an absorbed ID answers its kept record with mergedFrom.", "title": "Ids" }, "description": "Comma-separated record IDs (up to 100); an absorbed ID answers its kept record with mergedFrom." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 with its zone: records created or changed at or after it.", "examples": [ "2026-10-01T00:00:00Z" ], "title": "Updatedsince" }, "description": "RFC 3339 with its zone: records created or changed at or after it." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "active (default), archived or all.", "examples": [ "active" ], "title": "Status" }, "description": "active (default), archived or all." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Customer companies of the company (absorbed ones never listed), by creation date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompanyPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Companies" ], "summary": "Create a customer company", "description": "Create a customer company through the same function as the UI (scope `companies:write`); `Idempotency-Key`\nis required.", "operationId": "createCompany", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created through the same function as the UI (history with actor api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompany" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the record; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the created record.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:write), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "COMPANY_NAME_TAKEN, IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After) or ACTION_OUTCOME_UNKNOWN (read the record before deciding; never repeated).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, OWNER_INVALID, COMPANY_LIMIT_REACHED or IDEMPOTENCY_KEY_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "website": { "type": "string", "maxLength": 500, "description": "HTTP or HTTPS address without credentials." }, "industry": { "type": "string", "maxLength": 120 }, "address": { "type": "string", "maxLength": 1000 }, "description": { "type": "string", "maxLength": 10000 }, "ownerId": { "type": [ "string", "null" ], "maxLength": 64, "description": "An active administrator or agent (GET /api/v1/members)." } } }, "examples": { "company": { "summary": "A new customer company", "value": { "name": "Acme Ibérica", "website": "https://acme.example.com", "industry": "Retail" } } } } } } } }, "/api/v1/companies/search": { "post": { "tags": [ "Companies" ], "summary": "Search customer companies", "description": "Search customer companies by name with `q` in the body (scope `companies:read`).", "operationId": "searchCompanies", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Customer companies whose name contains q.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompanyPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, FIELD_NOT_ALLOWED or VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Text searched in the name." }, "ids": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Only these records (an absorbed ID answers its kept record with mergedFrom)." }, "updatedSince": { "type": "string", "format": "date-time", "description": "RFC 3339 with offset." }, "status": { "type": "string", "enum": [ "active", "archived", "all" ], "default": "active" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": "string", "description": "nextCursor of the previous page, with the same filters." } } }, "examples": { "byName": { "summary": "Find a customer company", "value": { "q": "Acme", "status": "all" } } } } } } } }, "/api/v1/companies/{company_id}": { "get": { "tags": [ "Companies" ], "summary": "Read a customer company", "description": "A customer company with its `ETag` (scope `companies:read`); a merged ID answers the kept company with\n`mergedFrom`.", "operationId": "getCompany", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The customer company (the kept one after a merge, with mergedFrom) and its counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompany" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the record; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Companies" ], "summary": "Update a customer company", "description": "Change a customer company (scope `companies:write`) with optimistic concurrency (`If-Match`).", "operationId": "updateCompany", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The company after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompany" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the record; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:write), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "MERGED_RECORD (canonicalId), COMPANY_NAME_TAKEN, IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After) or ACTION_OUTCOME_UNKNOWN (read the record before deciding; never repeated).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"\" of the record; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, OWNER_INVALID or IF_MATCH_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "website": { "type": "string", "maxLength": 500, "description": "HTTP or HTTPS address without credentials." }, "industry": { "type": "string", "maxLength": 120 }, "address": { "type": "string", "maxLength": 1000 }, "description": { "type": "string", "maxLength": 10000 }, "ownerId": { "type": [ "string", "null" ], "maxLength": 64, "description": "An active administrator or agent (GET /api/v1/members)." }, "archived": { "type": "boolean", "description": "Archive or restore (never a deletion)." } }, "description": "Only the fields sent change. Send If-Match with the ETag you read." }, "examples": { "owner": { "summary": "New owner and industry", "value": { "ownerId": "3c1f2a9e-0000-4000-8000-000000000000", "industry": "Logistics" } } } } } } } }, "/api/v1/companies/{company_id}/contacts": { "get": { "tags": [ "Companies" ], "summary": "List the people of a customer company", "description": "The contacts linked to the company with their role (scope `companies:read`; contact fields with\n`contacts:read`).", "operationId": "listCompanyContacts", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "People of the company; a contact the source does not reach shows only its ID. Contact fields need contacts:read and the source's read fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompanyContacts" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/companies/{company_id}/contacts/{contact_id}": { "put": { "tags": [ "Companies" ], "summary": "Link a contact to a customer company", "description": "Link a contact the source reaches to the company, or change its role (scope `companies:write`).", "operationId": "linkCompanyContact", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The contact is linked to the company with this role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompanyContactLink" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:write) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND or CONTACT_NOT_FOUND (a contact the source does not reach answers the same).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "MERGED_RECORD (company or contact), COMPANY_ARCHIVED, IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After) or ACTION_OUTCOME_UNKNOWN (read the record before deciding; never repeated).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED or VALIDATION_ERROR (role of up to 120 characters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "role": { "type": "string", "maxLength": 120, "default": "", "description": "Role of the person in the company." } } }, "examples": { "role": { "summary": "Link a person with a role", "value": { "role": "Compras" } } } } } } }, "delete": { "tags": [ "Companies" ], "summary": "Unlink a contact from a customer company", "description": "Remove the link between the company and the contact (scope `companies:write`); neither record is deleted.", "operationId": "unlinkCompanyContact", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "204": { "description": "The link is gone; the contact and the company stay." }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:write) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND, CONTACT_NOT_FOUND or COMPANY_CONTACT_NOT_FOUND (they are not linked).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "MERGED_RECORD, IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After) or ACTION_OUTCOME_UNKNOWN (read the record before deciding; never repeated).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/companies/{company_id}/history": { "get": { "tags": [ "Companies" ], "summary": "Read the history of a customer company", "description": "Date, type, actor and changed fields of the company history, without bodies (scope `companies:read`).", "operationId": "getCompanyHistory", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "History of the company and of the companies merged into it: date, type, actor and changed fields; never note bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompanyHistory" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/companies/{company_id}/notes": { "post": { "tags": [ "Companies" ], "summary": "Add a note to a customer company", "description": "Add a note to the company history as the delegated user (scope `companies:write`).", "operationId": "addCompanyNote", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Company Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "The note is in the company history, written by the delegated user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCompanyNoteAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (companies:write), FEATURE_DISABLED or DELEGATED_USER_* (a note needs a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "COMPANY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "MERGED_RECORD (canonicalId), IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After) or ACTION_OUTCOME_UNKNOWN (read the record before deciding; never repeated).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED or VALIDATION_ERROR (text of 1-5000 characters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000 } } }, "examples": { "call": { "summary": "Note from the tool", "value": { "text": "Llamada de seguimiento: quiere el presupuesto anual." } } } } } } } }, "/api/v1/contacts": { "post": { "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Create a contact (scope `contacts:write`) with the fields allowed in the source, or link your `externalId`\nto the only exact match when the source's `linkOnExactMatch` is on. Never grants consents.", "operationId": "createContact", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (422 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created (result created) through the common contact service: contact.created with origin api.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "revision", "mergedFrom", "mergedRecordIds", "externalId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." } }, "description": "Fields are present only with contacts:read and when they are in the source's read fields; notes, conversations, deals and consents are never exposed." } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the contact; send it back as If-Match.", "schema": { "type": "string" } }, "Location": { "description": "URL of the created contact.", "schema": { "type": "string" } } } }, "200": { "description": "linkOnExactMatch of the source found exactly one contact: the externalId is linked to it (result linked) and nothing of the contact is overwritten. The read is recorded.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the contact; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "revision", "mergedFrom", "mergedRecordIds", "externalId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." } }, "description": "Fields are present only with contacts:read and when they are in the source's read fields; notes, conversations, deals and consents are never exposed." } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED (marketing.api or api.tasks), CONTACT_FIELD_FORBIDDEN, CONTACT_TAG_FORBIDDEN or CONTACT_CUSTOM_FIELD_FORBIDDEN (outside the source's permissions).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS, IDENTITY_EXISTS (email or phone of another contact with linkOnExactMatch off), AMBIGUOUS_IDENTITY (several matches), EXTERNAL_ID_TAKEN (with contactId), EXTERNAL_ID_CONFLICT or CONTACT_LIMIT_REACHED (the company's contact capacity is full).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, EXTERNAL_ID_REQUIRED (sources that reach only linked contacts), CONTACT_BODY_INVALID, CONTACT_FIELD_UNKNOWN (consents, suppressions, notes or the whole tag list), CONTACT_FIELD_REQUIRED, CONTACT_FIELD_INVALID, CONTACT_EMAIL_INVALID, CONTACT_LANGUAGE_INVALID, CONTACT_TAGS_INVALID, TIMEZONE_INVALID, PROFILING_OPT_OUT_LOCKED, HIDDEN_WHATSAPP_EMAIL, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "externalId": { "type": "string", "description": "Your customer ID for this source: 1-128 visible ASCII characters, never an email or a phone. Required when the source only reaches contacts linked to it (the default).", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$", "examples": [ "customer_872" ] }, "name": { "type": "string", "description": "Name of the contact.", "minLength": 1, "maxLength": 160 }, "email": { "type": [ "string", "null" ], "maxLength": 254, "description": "Needs the separate email permission. A new address never inherits the consents of the previous one." }, "phone": { "type": [ "string", "null" ], "maxLength": 40, "description": "Needs the separate phone permission." }, "company": { "type": [ "string", "null" ], "maxLength": 160 }, "language": { "type": "string", "description": "Language code, e.g. es or en-GB.", "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,4})?$" }, "tagsToAdd": { "type": "array", "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Tags to add; only tags allowed in the source. The other tags are never touched." }, "customValues": { "type": "object", "description": "Values of the custom fields allowed in the source, with their real types and options (null clears one). Definitions are never created." }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone (e.g. Europe/Madrid), stored with source api; it never replaces a zone declared by the contact." }, "profilingOptOut": { "type": "boolean", "enum": [ true ], "description": "Records the contact's objection to profiling; a key can never withdraw it." } }, "description": "Only fields, tags and custom fields allowed in the source. No consents: use /subscriptions/invite." }, "examples": { "erpCustomer": { "summary": "Customer of the ERP, linked to the source by externalId", "value": { "externalId": "customer_872", "name": "Contacto de ejemplo", "email": "cliente@example.com", "language": "es", "customValues": { "customer_tier": "professional" }, "tagsToAdd": [ "cliente_web" ] } } } } } } }, "get": { "tags": [ "Contacts" ], "summary": "List contacts", "description": "Contacts the source reaches with the fields it may read (scope `contacts:read`, feature `api.tasks`), by\ncursor; filters `ids` and `updatedSince`. Never a search term in the URL: use `POST /api/v1/contacts/search`.", "operationId": "listContacts", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated record IDs (up to 100); an absorbed ID answers its kept record with mergedFrom.", "title": "Ids" }, "description": "Comma-separated record IDs (up to 100); an absorbed ID answers its kept record with mergedFrom." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339 with its zone: records created or changed at or after it.", "examples": [ "2026-10-01T00:00:00Z" ], "title": "Updatedsince" }, "description": "RFC 3339 with its zone: records created or changed at or after it." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Contacts the source reaches (contactScope) with its read fields; every read is recorded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContactPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (contacts:read) or FEATURE_DISABLED (api.tasks; marketing.api alone is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/contacts/lookup": { "post": { "tags": [ "Contacts" ], "summary": "Find a contact by externalId", "description": "The contact linked to your `externalId` in this source (scope `contacts:read`). The externalId goes in the\nbody, never in the URL.", "operationId": "lookupContact", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The contact linked to the externalId in this source (canonical after a merge). The read is recorded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "revision", "mergedFrom", "mergedRecordIds", "externalId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." } }, "description": "Fields are present only with contacts:read and when they are in the source's read fields; notes, conversations, deals and consents are never exposed." } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the contact; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (contacts:read) or FEATURE_DISABLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "CONTACT_NOT_FOUND: no contact is linked to this externalId in this source.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "CONTACT_BODY_INVALID, CONTACT_FIELD_UNKNOWN, EXTERNAL_ID_REQUIRED, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE or EXTERNAL_ID_PHONE_SHAPE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "externalId" ], "properties": { "externalId": { "type": "string", "description": "Your customer ID for this source: 1-128 visible ASCII characters, never an email or a phone.", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$", "examples": [ "customer_872" ] } } }, "examples": { "byExternalId": { "summary": "Find the contact of your customer", "value": { "externalId": "customer_872" } } } } } } } }, "/api/v1/contacts/search": { "post": { "tags": [ "Contacts" ], "summary": "Search contacts", "description": "Search the contacts the source reaches (scope `contacts:read`, feature `api.tasks`) with `q` in the body: the\nname and, when the source may read them, the email and the phone.", "operationId": "searchContacts", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Contacts matching q in the name and, when the source may read them, the email and the phone (searchedFields).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContactPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (contacts:read) or FEATURE_DISABLED (api.tasks; marketing.api alone is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (q goes in the body), FIELD_NOT_ALLOWED or VALIDATION_ERROR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Text searched in the name and, when the source may read them, the email and the phone." }, "ids": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "description": "Only these records (an absorbed ID answers its kept record with mergedFrom)." }, "updatedSince": { "type": "string", "format": "date-time", "description": "RFC 3339 with offset." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": "string", "description": "nextCursor of the previous page, with the same filters." } } }, "examples": { "byName": { "summary": "Find a contact by name", "value": { "q": "Lucía", "limit": 20 } } } } } } } }, "/api/v1/contacts/{contact_id}": { "get": { "tags": [ "Contacts" ], "summary": "Read a contact", "description": "A contact the source reaches (scope `contacts:read`); a merged ID answers the kept contact with `mergedFrom`.", "operationId": "getContact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The canonical contact as the source sees it. Every read is recorded (source, key, contact and day).", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "revision", "mergedFrom", "mergedRecordIds", "externalId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." } }, "description": "Fields are present only with contacts:read and when they are in the source's read fields; notes, conversations, deals and consents are never exposed." } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the contact; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (contacts:read) or FEATURE_DISABLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "CONTACT_NOT_FOUND: not a contact of the company that the source reaches.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Contacts" ], "summary": "Update a contact", "description": "Change the allowed fields of a contact the source reaches (scope `contacts:write`) with optimistic\nconcurrency (`If-Match`).", "operationId": "updateContact", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The contact after the change (the same revision when nothing changed).", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "revision", "mergedFrom", "mergedRecordIds", "externalId", "createdAt" ], "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "type": "array", "items": { "type": "string" }, "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." } }, "description": "Fields are present only with contacts:read and when they are in the source's read fields; notes, conversations, deals and consents are never exposed." } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the contact; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED (marketing.api or api.tasks), CONTACT_FIELD_FORBIDDEN, CONTACT_TAG_FORBIDDEN or CONTACT_CUSTOM_FIELD_FORBIDDEN (outside the source's permissions).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "CONTACT_NOT_FOUND: not a contact the source reaches.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "409": { "description": "MERGED_RECORD (the contact was merged: canonicalId is the kept one) or IDENTITY_EXISTS.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current revision (currentRevision in the body, ETag header): read again and retry.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the contact; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "IF_MATCH_INVALID, CONTACT_BODY_INVALID, CONTACT_FIELD_UNKNOWN (consents, suppressions, notes or the whole tag list), CONTACT_FIELD_REQUIRED, CONTACT_FIELD_INVALID, CONTACT_EMAIL_INVALID, CONTACT_LANGUAGE_INVALID, CONTACT_TAGS_INVALID, TIMEZONE_INVALID, PROFILING_OPT_OUT_LOCKED, HIDDEN_WHATSAPP_EMAIL, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag of the contact.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Name of the contact.", "minLength": 1, "maxLength": 160 }, "email": { "type": [ "string", "null" ], "maxLength": 254, "description": "Needs the separate email permission. A new address never inherits the consents of the previous one." }, "phone": { "type": [ "string", "null" ], "maxLength": 40, "description": "Needs the separate phone permission." }, "company": { "type": [ "string", "null" ], "maxLength": 160 }, "language": { "type": "string", "description": "Language code, e.g. es or en-GB.", "pattern": "^[A-Za-z]{2,3}([-_][A-Za-z0-9]{2,4})?$" }, "tagsToAdd": { "type": "array", "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Tags to add; only tags allowed in the source. The other tags are never touched." }, "customValues": { "type": "object", "description": "Values of the custom fields allowed in the source, with their real types and options (null clears one). Definitions are never created." }, "timezone": { "type": [ "string", "null" ], "description": "IANA zone (e.g. Europe/Madrid), stored with source api; it never replaces a zone declared by the contact." }, "profilingOptOut": { "type": "boolean", "enum": [ true ], "description": "Records the contact's objection to profiling; a key can never withdraw it." }, "tagsToRemove": { "type": "array", "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "description": "Tags to remove; only tags allowed in the source." } }, "description": "Only the keys sent change. Send If-Match with the ETag you read." }, "examples": { "tier": { "summary": "New tier and a tag", "value": { "customValues": { "customer_tier": "enterprise" }, "tagsToAdd": [ "vip" ], "tagsToRemove": [ "cliente_web" ] } } } } } } } }, "/api/v1/contacts/{contact_id}/notes": { "get": { "tags": [ "Contacts" ], "summary": "Read the notes of a contact", "description": "The notes of a contact the source reaches (scope `contacts:read`, feature `api.tasks`).", "operationId": "listContactNotes", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Notes of the contact (the kept record after a merge), newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContactNotes" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (contacts:read) or FEATURE_DISABLED (api.tasks; marketing.api alone is not enough).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND: not a contact of the company that the source reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Contacts" ], "summary": "Add a note to a contact", "description": "Add a note as the delegated user (scope `contacts:write`, feature `api.tasks`), through the same function as\nthe UI.", "operationId": "addContactNote", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "The note, added by the delegated user through the same function as the UI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContactNoteAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (contacts:write), FEATURE_DISABLED (api.tasks), DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE (a note needs a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "MERGED_RECORD (canonicalId: write on the kept record), IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After) or ACTION_OUTCOME_UNKNOWN (read the record before deciding; never repeated).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (text of 1-5000 characters) or IDEMPOTENCY_KEY_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000 } } }, "examples": { "call": { "summary": "Note from the tool", "value": { "text": "Llamada de seguimiento: quiere el presupuesto anual." } } } } } } } }, "/api/v1/contacts/{contact_id}/score": { "get": { "tags": [ "Journeys" ], "summary": "Read the score of a contact", "description": "The score of a contact the source reaches and its entries, newest first (scope `journeys:read`).", "operationId": "getContactScore", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The score of the contact and its entries.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContactScore" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (journeys:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND: not a contact of the company that the source reaches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/contacts/{contact_id}/tasks": { "get": { "tags": [ "Contacts" ], "summary": "List the tasks of a contact", "description": "The same as `GET /api/v1/tasks?contactId=` (feature `api.tasks`): the live tasks of the contact whose area this\nkey can read.", "operationId": "listContactTasks", "parameters": [ { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Contact Id" } }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated kinds (up to 10), for example crm.activity,support.ticket.", "title": "Kind" }, "description": "Comma-separated kinds (up to 10), for example crm.activity,support.ticket." }, { "name": "area", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated areas (up to 10).", "title": "Area" }, "description": "Comma-separated areas (up to 10)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated statuses; open,in_progress,waiting,needs_review by default.", "title": "Status" }, "description": "Comma-separated statuses; open,in_progress,waiting,needs_review by default." }, { "name": "assigneeId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tasks of this user (or routing contact).", "title": "Assigneeid" }, "description": "Tasks of this user (or routing contact)." }, { "name": "assignee", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "me: tasks of the delegated user (X-AIO-Act-As or the default user).", "examples": [ "me" ], "title": "Assignee" }, "description": "me: tasks of the delegated user (X-AIO-Act-As or the default user)." }, { "name": "unassigned", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: tasks without assignee.", "examples": [ "true" ], "title": "Unassigned" }, "description": "true: tasks without assignee." }, { "name": "teamId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tasks of this team.", "title": "Teamid" }, "description": "Tasks of this team." }, { "name": "dueBefore", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly before.", "title": "Duebefore" }, "description": "RFC 3339: due strictly before." }, { "name": "dueAfter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly after.", "title": "Dueafter" }, "description": "RFC 3339: due strictly after." }, { "name": "overdue", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: tasks with the overdue signal.", "examples": [ "true" ], "title": "Overdue" }, "description": "true: tasks with the overdue signal." }, { "name": "signal", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated signals (any of them).", "title": "Signal" }, "description": "Comma-separated signals (any of them)." }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated priorities: low, normal, high, urgent.", "title": "Priority" }, "description": "Comma-separated priorities: low, normal, high, urgent." }, { "name": "dealId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked deal ID.", "title": "Dealid" }, "description": "Linked deal ID." }, { "name": "ticketId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked ticket ID.", "title": "Ticketid" }, "description": "Linked ticket ID." }, { "name": "conversationId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked conversation ID.", "title": "Conversationid" }, "description": "Linked conversation ID." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: tasks whose observed change (updatedAt) is at or after it.", "title": "Updatedsince" }, "description": "RFC 3339: tasks whose observed change (updatedAt) is at or after it." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "dueAt (default, without date last), -updatedAt, -priority or createdAt.", "examples": [ "dueAt" ], "title": "Sort" }, "description": "dueAt (default, without date last), -updatedAt, -priority or createdAt." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "The same page as GET /api/v1/tasks?contactId=: live tasks whose area this key can read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContactTasks" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks). Kinds whose area the key cannot read are simply left out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND: not a contact of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (contactId goes in the path), VALIDATION_ERROR (a filter, sort or limit) or DELEGATED_USER_REQUIRED (assignee=me without a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversations": { "get": { "tags": [ "Support" ], "summary": "List conversations", "description": "The inbox, latest activity first (support conversations with `support:read`; sales ones with `sequences:read`).\nSubjects and previews only with `support:content`.", "operationId": "listConversations", "parameters": [ { "name": "purpose", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "support (default), sales (sequences:read and crm.sequences) or all.", "examples": [ "support" ], "title": "Purpose" }, "description": "support (default), sales (sequences:read and crm.sequences) or all." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "open, pending, resolved or all.", "examples": [ "open" ], "title": "Status" }, "description": "open, pending, resolved or all." }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "email, whatsapp, social, voice, web or web_form.", "examples": [ "email" ], "title": "Channel" }, "description": "email, whatsapp, social, voice, web or web_form." }, { "name": "labelId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conversations with this label.", "title": "Labelid" }, "description": "Conversations with this label." }, { "name": "assigneeId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A user ID, unassigned or mine (the delegated user: X-AIO-Act-As or the source's default user).", "examples": [ "unassigned" ], "title": "Assigneeid" }, "description": "A user ID, unassigned or mine (the delegated user: X-AIO-Act-As or the source's default user)." }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "low, normal, high or urgent.", "examples": [ "high" ], "title": "Priority" }, "description": "low, normal, high or urgent." }, { "name": "snoozed", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: only snoozed; false: only those not snoozed.", "examples": [ "false" ], "title": "Snoozed" }, "description": "true: only snoozed; false: only those not snoozed." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Conversations of the inbox, latest activity first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; sequences:read for sales conversations), FEATURE_DISABLED (api.tasks; crm.sequences for sales conversations) or DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT (assigneeId=mine with an X-AIO-Act-As the source may not use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL), VALIDATION_ERROR (field) or DELEGATED_USER_REQUIRED (assigneeId=mine without a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversations/bulk": { "post": { "tags": [ "Support" ], "summary": "Apply a macro or actions to conversations", "description": "A macro or explicit actions on up to 100 support conversations as the delegated user (scope `support:execute`):\n`dryRun` returns the preview and its `previewToken`; the execution needs that token and an `Idempotency-Key`.", "operationId": "bulkUpdateConversations", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "dryRun: the preview and its previewToken; execution: succeeded, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationBulkAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:execute), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_REQUIRED (send X-AIO-Act-As or set a default user), DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND (missing or of another company) or MACRO_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "PREVIEW_STALE (run dryRun again), TICKET_MERGED, MACRO_EMPTY, LABEL_LIMIT, ASSIGNEE_NOT_IN_TEAM, ASSIGNEE_AT_CAPACITY, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (more than 100 conversations, macroId and actions together, previewToken missing: confirmation_required), SALES_CONVERSATION, NO_CHANGES or LABEL_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "input" ], "properties": { "input": { "type": "object", "additionalProperties": false, "required": [ "conversationIds" ], "properties": { "conversationIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 64 }, "description": "Up to 100 support conversations (the limit of the app)." }, "macroId": { "type": "string", "maxLength": 64, "description": "A macro (GET /api/v1/macros), or send actions." }, "actions": { "type": "object", "additionalProperties": false, "description": "Explicit actions (instead of macroId): at least one; a label is never added and removed at once.", "properties": { "status": { "type": "string", "enum": [ "open", "pending", "resolved" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assigneeId": { "type": "string", "maxLength": 64, "description": "A user ID, mine (the delegated user) or unassigned." }, "addLabelIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } }, "removeLabelIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } } } }, "previewToken": { "type": "string", "pattern": "^[a-f0-9]{64}$", "description": "Required to execute: the previewToken of the dryRun with the same input." } } }, "dryRun": { "type": "boolean", "default": false, "description": "true: only the preview (changes and previewToken); nothing changes and no Idempotency-Key is needed." } } }, "examples": { "preview": { "summary": "1) Preview a macro on two conversations", "value": { "dryRun": true, "input": { "conversationIds": [ "c0de0000-0000-4000-8000-000000000001", "c0de0000-0000-4000-8000-000000000002" ], "macroId": "9a1b0000-0000-4000-8000-000000000000" } } }, "execute": { "summary": "2) Apply it with the previewToken of the preview", "value": { "input": { "conversationIds": [ "c0de0000-0000-4000-8000-000000000001", "c0de0000-0000-4000-8000-000000000002" ], "macroId": "9a1b0000-0000-4000-8000-000000000000", "previewToken": "3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f" } } } } } } } } }, "/api/v1/conversations/search": { "post": { "tags": [ "Support" ], "summary": "Search conversations", "description": "The inbox with its filters and a text search in the body (`q` needs `support:content`).", "operationId": "searchConversations", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Conversations matching the search, latest activity first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read or sequences:read; support:content for q), FEATURE_DISABLED or DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT (assigneeId=mine with an X-AIO-Act-As the source may not use).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field) or DELEGATED_USER_REQUIRED (assigneeId=mine without a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Searches subjects and message bodies (needs support:content) and, of the contacts the source reaches (contactScope), only the fields it may read: name, email and phone (also by its digits). See searchedFields." }, "purpose": { "type": "string", "enum": [ "support", "sales", "all" ] }, "status": { "type": "string", "enum": [ "open", "pending", "resolved", "all" ] }, "channel": { "type": "string", "enum": [ "email", "whatsapp", "social", "voice", "web", "web_form" ] }, "labelId": { "type": "string" }, "assigneeId": { "type": "string", "description": "A user ID, unassigned or mine (the delegated user: X-AIO-Act-As or the source's default user)." }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "snoozed": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string" } } }, "examples": { "text": { "summary": "Open conversations that mention an invoice", "value": { "q": "factura", "status": "open", "limit": 20 } } } } } } } }, "/api/v1/conversations/{conversation_id}": { "get": { "tags": [ "Support" ], "summary": "Read a conversation", "description": "A conversation with its ticket and tasks; subject and preview only with `support:content`.", "operationId": "getConversation", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The conversation (subject and preview only with support:content).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversation" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; sequences:read for a sales conversation; support:content for bodies) or FEATURE_DISABLED (api.tasks; crm.sequences for sales conversations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversations/{conversation_id}/actions/{action}": { "post": { "tags": [ "Support" ], "summary": "Run an action of a conversation", "description": "The actions of the conversation's ticket (the same checks, `dryRun` and idempotency as the task action).", "operationId": "runConversationAction", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "mark_read": { "summary": "Mark as read (sales_conversation.mark_read; sequences:execute, service)", "value": { "input": {} } }, "reply": { "summary": "Reply from the mailbox (sales_conversation.reply; sequences:execute, owner)", "value": { "input": { "text": "Hola Lucía, ya hemos reenviado la factura de septiembre.", "expectedLastMessageId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "add_note": { "summary": "Add an internal note (support_case.add_note; support:write, delegated)", "value": { "input": { "text": "Lo revisa Facturación esta tarde.", "mentionUserIds": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] } } }, "apply_macro": { "summary": "Apply a macro (support_case.apply_macro; support:execute, delegated)", "value": { "input": { "macroId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "previewToken": "9ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d79ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d7" } } }, "apply_macro.dryRun": { "summary": "Apply a macro: dryRun returns the confirmation token(s) previewToken", "value": { "dryRun": true, "input": { "macroId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "assign": { "summary": "Assign (support_case.assign; support:execute, service)", "value": { "input": { "assigneeId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "hand_off": { "summary": "Hand off to a person (support_case.hand_off; support:execute, service)", "value": { "input": {} } }, "merge_into": { "summary": "Merge into another ticket (support_case.merge_into; support:execute, service)", "value": { "input": { "targetTicketId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "public_reply": { "summary": "Public reply on the portal (support_case.public_reply; support:execute, delegated)", "value": { "input": { "text": "Hola Lucía, ya hemos reenviado la factura de septiembre." } } }, "reopen": { "summary": "Reopen (support_case.reopen; support:execute, service)", "value": { "input": {} } }, "resolve": { "summary": "Resolve (support_case.resolve; support:execute, service)", "value": { "input": {} } }, "return_to_ai": { "summary": "Return to the AI (support_case.return_to_ai; support:execute, service)", "value": { "input": {} } }, "set_labels": { "summary": "Set labels (support_case.set_labels; support:write, service)", "value": { "input": { "labelIds": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] } } }, "set_stage": { "summary": "Change stage (support_case.set_stage; support:write, service)", "value": { "input": { "stageId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "set_status": { "summary": "Change status (support_case.set_status; support:execute, service)", "value": { "input": { "sourceStatus": "waiting_customer" } } }, "set_team": { "summary": "Change team (support_case.set_team; support:write, service)", "value": { "input": { "teamId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "snooze": { "summary": "Snooze (support_case.snooze; support:execute, delegated)", "value": { "input": { "until": "2026-10-01T09:00:00Z" } } }, "split": { "summary": "Split (support_case.split; support:execute, service)", "value": { "input": { "title": "Segunda factura duplicada" } } }, "unsnooze": { "summary": "Wake up now (support_case.unsnooze; support:execute, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/conversations/{conversation_id}/labels": { "get": { "tags": [ "Support" ], "summary": "Read the labels of a conversation", "description": "The labels of a conversation (scope `support:read`).", "operationId": "listConversationLabels", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Labels of the conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationLabels" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; sequences:read for a sales conversation; support:content for bodies) or FEATURE_DISABLED (api.tasks; crm.sequences for sales conversations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversations/{conversation_id}/messages": { "get": { "tags": [ "Support" ], "summary": "Read the messages of a conversation", "description": "The messages of a conversation, oldest first (scope `support:content`).", "operationId": "listConversationMessages", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Messages of the conversation, oldest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationMessages" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; sequences:read for a sales conversation; support:content for bodies) or FEATURE_DISABLED (api.tasks; crm.sequences for sales conversations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversations/{conversation_id}/notes": { "get": { "tags": [ "Support" ], "summary": "Read the internal notes of a conversation", "description": "The internal notes of a conversation, newest first (scope `support:content`).", "operationId": "listConversationNotes", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Internal notes of the conversation, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationNotes" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; sequences:read for a sales conversation; support:content for bodies) or FEATURE_DISABLED (api.tasks; crm.sequences for sales conversations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversations/{conversation_id}/snooze": { "get": { "tags": [ "Support" ], "summary": "Read the snooze of a conversation", "description": "When the conversation wakes up, if it is snoozed (scope `support:read`).", "operationId": "getConversationSnooze", "parameters": [ { "name": "conversation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversation Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The snooze of the conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversationSnooze" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; sequences:read for a sales conversation; support:content for bodies) or FEATURE_DISABLED (api.tasks; crm.sequences for sales conversations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversions": { "get": { "tags": [ "Conversions" ], "summary": "List conversions", "description": "Declared conversions, orders and won deals with their attribution and task (scope `conversions:read`; feature\n`marketing.tracking`); `status=unreconciled` lists the ones to reconcile.", "operationId": "listConversions", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated statuses (reported, paid_declared, partially_refunded, refunded, review, unreconciled, reconciled); unreconciled for the ones to reconcile.", "examples": [ "unreconciled" ], "title": "Status" }, "description": "Comma separated statuses (reported, paid_declared, partially_refunded, refunded, review, unreconciled, reconciled); unreconciled for the ones to reconcile." }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "conversion, order or deal_won.", "title": "Kind" }, "description": "conversion, order or deal_won." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Conversions, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversionPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (conversions:read) or FEATURE_DISABLED (api.tasks or marketing.tracking).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR, CONVERSION_STATUS_INVALID or CONVERSION_KIND_INVALID (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversions/{conversion_id}": { "get": { "tags": [ "Conversions" ], "summary": "Read a conversion", "description": "A conversion with its observations, decision, candidates, manual links, task and `ETag` (scope\n`conversions:read`).", "operationId": "getConversion", "parameters": [ { "name": "conversion_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Conversion Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The conversion with its observations, decision, candidates, task and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiConversion" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the conversion.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (conversions:read) or FEATURE_DISABLED (api.tasks or marketing.tracking).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/conversions/{resource_id}/actions/{action}": { "post": { "tags": [ "Conversions" ], "summary": "Run an action of a conversion", "description": "Run an action of a conversions resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runConversionAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "link": { "summary": "Link by hand (marketing_conversion.link; conversions:admin, delegated)", "value": { "input": { "target": { "type": "deal", "id": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" }, "reason": "Confirmed with the customer by phone" } } }, "revoke_link": { "summary": "Revoke the link (marketing_conversion.revoke_link; conversions:admin, delegated)", "value": { "input": { "linkId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "reason": "Confirmed with the customer by phone" } } } } } } } } }, "/api/v1/csat/deliveries": { "get": { "tags": [ "CSAT" ], "summary": "List CSAT invitations", "description": "Automatic satisfaction survey invitations, newest first (scope `csat:read`, feature `support.csat_auto`).", "operationId": "listCsatDeliveries", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated delivery statuses (scheduled, uncertain, failed…).", "examples": [ "uncertain" ], "title": "Status" }, "description": "Comma separated delivery statuses (scheduled, uncertain, failed…)." }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A reason code (cooldown, opted_out, lease_expired…).", "examples": [ "cooldown" ], "title": "Reason" }, "description": "A reason code (cooldown, opted_out, lease_expired…)." }, { "name": "conversationId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The invitations of this conversation.", "title": "Conversationid" }, "description": "The invitations of this conversation." }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "automatic or manual.", "examples": [ "automatic" ], "title": "Source" }, "description": "automatic or manual." }, { "name": "needsReview", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: only uncertain or paused invitations.", "examples": [ "true" ], "title": "Needsreview" }, "description": "true: only uncertain or paused invitations." }, { "name": "answered", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: only answered surveys; false: only unanswered.", "examples": [ "false" ], "title": "Answered" }, "description": "true: only answered surveys; false: only unanswered." }, { "name": "closedFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: closes at or after it.", "examples": [ "2026-10-01T00:00:00Z" ], "title": "Closedfrom" }, "description": "RFC 3339: closes at or after it." }, { "name": "closedTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: closes at or before it.", "examples": [ "2026-10-31T23:59:59Z" ], "title": "Closedto" }, "description": "RFC 3339: closes at or before it." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "CSAT invitations, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCsatDeliveryPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (csat:read) or FEATURE_DISABLED (api.tasks or support.csat_auto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND (conversationId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/csat/deliveries/{delivery_id}": { "get": { "tags": [ "CSAT" ], "summary": "Read a CSAT invitation", "description": "An invitation with its attempts, team actions, task status and `ETag` (scope `csat:read`, feature\n`support.csat_auto`).", "operationId": "getCsatDelivery", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Delivery Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The invitation with its attempts, team actions and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCsatDelivery" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the invitation; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (csat:read) or FEATURE_DISABLED (api.tasks or support.csat_auto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CSAT_DELIVERY_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/csat/deliveries/{delivery_id}/actions/{action}": { "post": { "tags": [ "CSAT" ], "summary": "Run an action of a CSAT invitation", "description": "send_now, cancel, retry or review of an invitation: the same checks, `dryRun` and idempotency as the task\naction.", "operationId": "runCsatDeliveryAction", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Delivery Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "cancel": { "summary": "Cancel the invitation (csat_delivery.cancel; csat:execute, service)", "value": { "input": {} } }, "retry": { "summary": "Retry the invitation (csat_delivery.retry; csat:execute, service)", "value": { "input": {} } }, "review": { "summary": "Review the invitation (csat_delivery.review; csat:admin, delegated)", "value": { "input": { "decision": "confirm_accepted", "reason": "Confirmed with the customer by phone" } } }, "send_now": { "summary": "Send now (csat_delivery.send_now; csat:execute, service)", "value": { "input": {} } } } } } } } }, "/api/v1/csat/surveys": { "get": { "tags": [ "CSAT" ], "summary": "List the CSAT surveys of a conversation", "description": "The close cycles of a support conversation with their satisfaction survey (scope `csat:read`): rating and state,\nthe comment only with `support:content`; never a survey link or token.", "operationId": "listCsatSurveys", "parameters": [ { "name": "conversationId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Required: a support conversation (an ID, never personal data).", "title": "Conversationid" }, "description": "Required: a support conversation (an ID, never personal data)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Close cycles of the conversation with their survey (never a link or token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCsatSurveys" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (csat:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONVERSATION_NOT_FOUND: it does not exist, belongs to another company or is a sales conversation (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (conversationId is required).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/customer-notes": { "get": { "tags": [ "Support" ], "summary": "List customer messages", "description": "Messages customers left for the team, newest first, with their alerts (scope `support:read`); the text only with\n`support:content`.", "operationId": "listCustomerNotes", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "pending (default), done or all.", "examples": [ "pending" ], "title": "Status" }, "description": "pending (default), done or all." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Customer messages, newest first; the text only with support:content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCustomerNotePage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/customer-notes/{note_id}": { "get": { "tags": [ "Support" ], "summary": "Read a customer message", "description": "A customer message with its alerts, task status and `ETag` (scope `support:read`).", "operationId": "getCustomerNote", "parameters": [ { "name": "note_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Note Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The customer message with its alerts and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCustomerNote" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the customer message; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CUSTOMER_MESSAGE_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "patch": { "tags": [ "Support" ], "summary": "Update a customer message", "description": "Mark a customer message as done or pending through the same function as the app (scope `support:execute`;\n`If-Match` required).", "operationId": "updateCustomerNote", "parameters": [ { "name": "note_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Note Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The customer message after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiCustomerNote" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the customer message; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:execute) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CUSTOMER_MESSAGE_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"h:<16 hex>\" of the customer message; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (status is pending or done) or IF_MATCH_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status" ], "description": "One call to the customer message update of the app; send If-Match with the ETag you read.", "properties": { "status": { "type": "string", "enum": [ "pending", "done" ] } } }, "examples": { "done": { "summary": "Mark it as done from the tool", "value": { "status": "done" } } } } } } } }, "/api/v1/customer-notes/{resource_id}/actions/{action}": { "post": { "tags": [ "Support" ], "summary": "Run an action of a customer message", "description": "Run an action of a customer-notes resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runCustomerNoteAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "mark_done": { "summary": "Mark as done (customer_message.mark_done; support:execute, service)", "value": { "input": {} } }, "reopen": { "summary": "Reopen (customer_message.reopen; support:execute, service)", "value": { "input": {} } }, "retry_notifications": { "summary": "Retry the failed alerts (customer_message.retry_notifications; support:execute, service)", "value": { "input": {} } }, "review_notification": { "summary": "Review an unconfirmed alert (customer_message.review_notification; support:admin, delegated)", "value": { "input": { "jobId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "action": "retry", "confirmPossibleDuplicate": true } } } } } } } } }, "/api/v1/deals": { "get": { "tags": [ "Deals" ], "summary": "List deals", "description": "Deals with their warnings and next follow-up, by cursor (scope `deals:read`); only IDs go in the URL.", "operationId": "listDeals", "parameters": [ { "name": "pipelineId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deals of this sales pipeline.", "title": "Pipelineid" }, "description": "Deals of this sales pipeline." }, { "name": "stageId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deals in this stage.", "title": "Stageid" }, "description": "Deals in this stage." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deals of this owner (user ID), unassigned, or me (the delegated user).", "examples": [ "unassigned" ], "title": "Ownerid" }, "description": "Deals of this owner (user ID), unassigned, or me (the delegated user)." }, { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "open, won, lost, archived or all; without it, the active deals (open, won and lost).", "examples": [ "open" ], "title": "State" }, "description": "open, won, lost, archived or all; without it, the active deals (open, won and lost)." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deals of this contact ID (never personal data in the URL).", "title": "Contactid" }, "description": "Deals of this contact ID (never personal data in the URL)." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: changed at or after it.", "title": "Updatedsince" }, "description": "RFC 3339: changed at or after it." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Deals of the company by creation date.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDealPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (deals:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Deals" ], "summary": "Create a deal", "description": "Create a deal through the same service as the UI (scope `deals:write`; `Idempotency-Key` required). Without\n`ownerId` the delegated user owns it when admin or agent.", "operationId": "createDeal", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created through the same service as the UI (history and deal.created with actor api).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDeal" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the deal; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new deal (/api/v1/deals/{id}).", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (deals:write; deals:execute to enter or leave a won or lost stage), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND, PIPELINE_NOT_FOUND or STAGE_NOT_FOUND (another company's record answers the same).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN, MERGED_RECORD (canonicalId: use the kept contact), DEAL_ARCHIVED, STAGE_NOT_CONFIGURED, STAGE_ARCHIVED or PIPELINE_ARCHIVED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), OWNER_INVALID, LOST_REASON_REQUIRED, STAGE_REQUIRED_FIELDS, STAGE_PIPELINE_MISMATCH, CUSTOM_FIELD_UNKNOWN, EXPECTED_CLOSE_INVALID, PROBABILITY_INVALID, MONEY_*, CURRENCY_* or STAGE_REQUIREMENTS_UNMET (stageId, requirements: requirementId, type, met, reason and config of each one) when the stage asks for a completed follow-up, a completed playbook or an approval the deal does not have yet — reason ACTIVITY_REQUIRED, PLAYBOOK_REQUIRED, APPROVAL_REQUIRED, APPROVAL_PENDING (approvalRequestId: wait for the decision), APPROVAL_REJECTED, APPROVAL_EXPIRED or APPROVAL_STALE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title", "contactId" ], "description": "Creating a deal in a won or lost stage also needs deals:execute.", "properties": { "title": { "type": "string", "minLength": 2, "maxLength": 255 }, "amount": { "type": [ "string", "integer" ], "description": "Decimal string (\"1200.50\") or a whole number; never a float." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ownerId": { "type": [ "string", "null" ], "maxLength": 64, "description": "By default the delegated user when admin or agent; null: unassigned." }, "expectedClose": { "type": [ "string", "null" ], "format": "date" }, "stage": { "type": "string", "enum": [ "lead", "qualified", "proposal", "negotiation", "won", "lost" ], "description": "won or lost needs deals:execute." }, "pipelineId": { "type": "string", "maxLength": 64 }, "stageId": { "type": "string", "maxLength": 64 }, "lostReason": { "type": "string", "maxLength": 1000 }, "probabilityOverride": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "forecastCategory": { "type": "string", "enum": [ "pipeline", "best_case", "commit", "omitted" ] }, "customValues": { "type": "object", "maxProperties": 100, "additionalProperties": true }, "contactId": { "type": "string", "maxLength": 64 }, "source": { "type": "string", "maxLength": 120 } } }, "examples": { "deal": { "summary": "A deal from the tool", "value": { "title": "Renovación anual", "contactId": "77aa0c2e-0000-4000-8000-000000000000", "amount": "1200.00", "currency": "EUR", "expectedClose": "2026-11-30" } } } } } } } }, "/api/v1/deals/{deal_id}": { "get": { "tags": [ "Deals" ], "summary": "Read a deal", "description": "The deal card with its warnings, next follow-up and `ETag` (scope `deals:read`).", "operationId": "getDeal", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The deal card with its warnings and next follow-up, and its ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDeal" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the deal; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (deals:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "DEAL_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Deals" ], "summary": "Update a deal", "description": "Change a deal with one call of the deal service (scope `deals:write`; `deals:execute` to enter or leave a won or\nlost stage) and optimistic concurrency (`If-Match`).", "operationId": "updateDeal", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The deal after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDeal" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the deal; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (deals:write; deals:execute to enter or leave a won or lost stage), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "DEAL_NOT_FOUND, PIPELINE_NOT_FOUND or STAGE_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN, MERGED_RECORD (canonicalId: use the kept contact), DEAL_ARCHIVED, STAGE_NOT_CONFIGURED, STAGE_ARCHIVED or PIPELINE_ARCHIVED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"\" of the deal; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), OWNER_INVALID, LOST_REASON_REQUIRED, STAGE_REQUIRED_FIELDS, STAGE_PIPELINE_MISMATCH, CUSTOM_FIELD_UNKNOWN, EXPECTED_CLOSE_INVALID, PROBABILITY_INVALID, MONEY_*, CURRENCY_* or STAGE_REQUIREMENTS_UNMET (stageId, requirements: requirementId, type, met, reason and config of each one) when the stage asks for a completed follow-up, a completed playbook or an approval the deal does not have yet — reason ACTIVITY_REQUIRED, PLAYBOOK_REQUIRED, APPROVAL_REQUIRED, APPROVAL_PENDING (approvalRequestId: wait for the decision), APPROVAL_REJECTED, APPROVAL_EXPIRED or APPROVAL_STALE; IF_MATCH_INVALID for a malformed If-Match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only the fields sent change, with one call of the deal service. Moving the deal into or out of a won or lost stage also needs deals:execute. Send If-Match.", "properties": { "title": { "type": "string", "minLength": 2, "maxLength": 255 }, "amount": { "type": [ "string", "integer" ], "description": "Decimal string (\"1200.50\") or a whole number; never a float." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "ownerId": { "type": [ "string", "null" ], "maxLength": 64, "description": "An active administrator or agent; null: unassigned." }, "expectedClose": { "type": [ "string", "null" ], "format": "date" }, "stage": { "type": "string", "enum": [ "lead", "qualified", "proposal", "negotiation", "won", "lost" ], "description": "won or lost needs deals:execute." }, "pipelineId": { "type": "string", "maxLength": 64 }, "stageId": { "type": "string", "maxLength": 64 }, "lostReason": { "type": "string", "maxLength": 1000 }, "probabilityOverride": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 100 }, "forecastCategory": { "type": "string", "enum": [ "pipeline", "best_case", "commit", "omitted" ] }, "customValues": { "type": "object", "maxProperties": 100, "additionalProperties": true } } }, "examples": { "forecast": { "summary": "New amount and expected close", "value": { "amount": "1500.00", "expectedClose": "2026-12-15", "forecastCategory": "commit" } } } } } } } }, "/api/v1/deals/{deal_id}/history": { "get": { "tags": [ "Deals" ], "summary": "Read the history of a deal", "description": "Date, type, actor and changed fields of the deal's history, without values (scope `deals:read`).", "operationId": "getDealHistory", "parameters": [ { "name": "deal_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Deal Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Changes of the deal: date, type, actor (user, api or system) and changed fields; never values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDealHistory" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (deals:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "DEAL_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (limit 1-100).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/deals/{resource_id}/actions/{action}": { "post": { "tags": [ "Deals" ], "summary": "Run an action of a deal", "description": "Run an action of a deals resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runDealAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function; update_deal with stageId, win and reopen: STAGE_REQUIREMENTS_UNMET (stageId, requirements: requirementId, type, met, reason and config of each one) when the stage asks for a completed follow-up, a completed playbook or an approval the deal does not have yet — reason ACTIVITY_REQUIRED, PLAYBOOK_REQUIRED, APPROVAL_REQUIRED, APPROVAL_PENDING (approvalRequestId: wait for the decision), APPROVAL_REJECTED, APPROVAL_EXPIRED or APPROVAL_STALE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "archive": { "summary": "Archive (opportunity.archive; deals:execute, service)", "value": { "input": {} } }, "lose": { "summary": "Mark as lost (opportunity.lose; deals:execute, service)", "value": { "input": { "lostReason": "Price" } } }, "reopen": { "summary": "Reopen (opportunity.reopen; deals:execute, service)", "value": { "input": {} } }, "restore": { "summary": "Restore (opportunity.restore; deals:execute, service)", "value": { "input": {} } }, "schedule_next_activity": { "summary": "Schedule the next activity (opportunity.schedule_next_activity; deals:write, service)", "value": { "input": { "title": "Llamar para renovar", "dueAt": "2026-10-01T09:00:00Z" } } }, "update_deal": { "summary": "Update the deal (opportunity.update_deal; deals:write, service)", "value": { "input": { "amount": "12000.00", "currency": "EUR", "expectedClose": "2026-11-30" } } }, "win": { "summary": "Mark as won (opportunity.win; deals:execute, service)", "value": { "input": {} } } } } } } } }, "/api/v1/duplicates": { "get": { "tags": [ "Duplicates" ], "summary": "List duplicate candidates", "description": "Candidate pairs of contacts or customer companies (scope `duplicates:read`, features `api.tasks` and `crm.merge`):\nthe same detection as the UI, by cursor. Act on a pair with `POST /api/v1/duplicates/{entity}/{idA}/{idB}/actions/…`\nor through its task `crm.duplicate_review:::`.", "operationId": "listDuplicates", "parameters": [ { "name": "entity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "contact (default) or company.", "examples": [ "contact" ], "title": "Entity" }, "description": "contact (default) or company." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "pending (default) or dismissed.", "examples": [ "pending" ], "title": "Status" }, "description": "pending (default) or dismissed." }, { "name": "recordId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the pairs or merges of this record (an ID, never personal data).", "title": "Recordid" }, "description": "Only the pairs or merges of this record (an ID, never personal data)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Candidate pairs (and groups) of crm_merge's detection with reasons, contradictions and taskIds; contact fields follow the source's read fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiDuplicatePage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (duplicates:read) or FEATURE_DISABLED (api.tasks or crm.merge).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "RESOURCE_NOT_FOUND: recordId is not a record of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/duplicates/{entity}/{id_a}/{id_b}/actions/{action}": { "post": { "tags": [ "Duplicates" ], "summary": "Run an action of a duplicate pair", "description": "`dismiss`, `restore` (`duplicates:write`), `preview_merge` and `merge` (`duplicates:admin`, a delegated\nadministrator) of a pair, in any order of its IDs: the same action, checks and idempotency as the task. `merge`\nneeds `planHash` and `expiresAt` of its dryRun (the native preview) and a `reason`.", "operationId": "runDuplicateAction", "parameters": [ { "name": "entity", "in": "path", "required": true, "schema": { "type": "string", "title": "Entity" } }, { "name": "id_a", "in": "path", "required": true, "schema": { "type": "string", "title": "Id A" } }, { "name": "id_b", "in": "path", "required": true, "schema": { "type": "string", "title": "Id B" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "merge.dryRun": { "summary": "Merge: dryRun returns the confirmation token(s) planHash, expiresAt", "value": { "dryRun": true, "input": { "survivorId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "reason": "Same customer: same email and phone" } } }, "preview_merge": { "summary": "Merge preview (duplicate_pair.preview_merge; duplicates:admin, delegated)", "value": { "input": { "survivorId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "preview_merge.dryRun": { "summary": "Merge preview: dryRun returns the confirmation token(s)", "value": { "dryRun": true, "input": { "survivorId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "restore": { "summary": "Review the pair again (duplicate_pair.restore; duplicates:write, delegated)", "value": { "input": {} } }, "dismiss": { "summary": "Not duplicates (with the fingerprint you saw)", "value": { "input": { "fingerprint": "0000000000000000000000000000000000000000000000000000000000000000" } } }, "previewMerge": { "summary": "dryRun of merge: the preview and its tokens", "value": { "dryRun": true, "input": { "survivorId": "3c1f2a9e-0000-4000-8000-000000000000", "choices": { "name": "survivor" } } } }, "merge": { "summary": "Merge with the tokens of the dryRun", "value": { "input": { "survivorId": "3c1f2a9e-0000-4000-8000-000000000000", "choices": { "name": "survivor" }, "reason": "Same person", "planHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "expiresAt": "2026-10-05T10:15:00Z" } } } } } } } } }, "/api/v1/event-types": { "get": { "tags": [ "Events" ], "summary": "Read the catalog of the event feed", "description": "Every type of the event feed with its area, scope and feature, whether this key can read it now and the resource\nthat reads each aggregate (scope `events:read`, feature `api.tasks`).", "operationId": "listEventTypes", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The catalog of the feed: area, scope, feature and availability of each type, and how to read each aggregate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiEventTypes" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (events:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/events": { "get": { "tags": [ "Events" ], "summary": "Read the event feed", "description": "The company's facts in order (scope `events:read`, feature `api.tasks`): only the types whose area the key can\nread (`:read`). IDs, type and version only: read the record afterwards with `readWith` of the catalog.", "operationId": "listEvents", "parameters": [ { "name": "types", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated event types (up to 30) of GET /api/v1/event-types; all the types the key can read by default.", "examples": [ "deal.won,deal.lost" ], "title": "Types" }, "description": "Comma separated event types (up to 30) of GET /api/v1/event-types; all the types the key can read by default." }, { "name": "after", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same types). Without it the feed starts at the oldest fact kept.", "title": "After" }, "description": "nextCursor of the previous page (same types). Without it the feed starts at the oldest fact kept." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-500 (100 by default).", "examples": [ "100" ], "title": "Limit" }, "description": "1-500 (100 by default)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Facts after the cursor, in order and at least once, as the «despertador» payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiEventFeedPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (events:read; or :read of a type asked in types, with requiredScopes) or FEATURE_DISABLED (api.tasks, or the feature of that area). Types of areas the key cannot read are simply left out without types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, or made for another company, source or types.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "410": { "description": "CURSOR_EXPIRED: the retention removed the facts before it; start again without after.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field types: unknown_value, not_in_feed or range; limit 1-500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Events" ], "summary": "Declare one event", "description": "One fact per request (scope `events:write`). 202 only after the event and its deliveries are stored;\nretries reuse the same `eventId`. The server fixes the company, source, trust (`clientDeclared`),\nmode (`live`) and reception time.", "operationId": "submitEvent", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional; when sent it must equal eventId.", "title": "Idempotency-Key" }, "description": "Optional; when sent it must equal eventId." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "202": { "description": "Accepted: the event and its deliveries are stored (duplicate false), or the same event was already accepted (duplicate true). It is not an action completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "eventId", "eventType", "status", "receivedAt", "trust", "mode", "deliveries", "statusUrl" ], "properties": { "id": { "type": "string", "description": "RouterClip event ID (use it to read the receipt)." }, "eventId": { "type": "string", "description": "Your eventId." }, "eventType": { "type": "string", "enum": [ "conversion.reported", "order.paid", "order.refunded", "custom" ] }, "schemaVersion": { "type": "integer" }, "status": { "type": "string", "enum": [ "accepted" ], "description": "Durable reception; not an action completed." }, "duplicate": { "type": "boolean", "description": "Only in POST answers: true when the same event had already been accepted." }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "trust": { "type": "string", "enum": [ "clientDeclared" ] }, "mode": { "type": "string", "enum": [ "live", "import" ], "description": "live for POST /api/v1/events; import for events loaded with POST /api/v1/events/import." }, "contactResolved": { "type": "boolean" }, "normalization": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "normalized" ] }, "money": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "amountMinor": { "type": "integer" }, "exponent": { "type": "integer" }, "currency": { "type": "string" } } } } }, "attribution": { "type": [ "object", "null" ], "properties": { "basis": { "type": "string", "enum": [ "browser", "contact", "none" ] }, "site": { "type": [ "string", "null" ] } }, "description": "What attribution can use (conversions and orders); the decision is the delivery of marketing.attribution." }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "consumer": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed", "skipped" ] }, "attempts": { "type": "integer" }, "lastError": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "description": "One receipt per consumer, without payload. done does not mean a message was delivered." }, "statusUrl": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Location": { "description": "The receipt URL (statusUrl).", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (events:write), FEATURE_DISABLED (marketing.api) or EVENT_TYPE_FORBIDDEN (type not allowed in the source).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same eventId, another body) or SUBJECT_IDENTITY_CONFLICT (identities that disagree).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "Invalid event: EVENT_BODY_INVALID, EVENT_FIELD_NOT_ALLOWED, CONTEXT_FIELD_NOT_ALLOWED, EVENT_ID_INVALID, IDEMPOTENCY_KEY_MISMATCH, EVENT_TYPE_UNKNOWN, EVENT_TYPE_NOT_ALLOWED, EVENT_TYPE_RESERVED, EVENT_TRUST_RESERVED, EVENT_SCHEMA_VERSION, EVENT_OCCURRED_AT_INVALID, EVENT_OCCURRED_IN_FUTURE, EVENT_OCCURRED_TOO_OLD, SUBJECT_REQUIRED, SUBJECT_INVALID, SUBJECT_UNRESOLVED, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE, ANONYMOUS_ID_INVALID, ANONYMOUS_ID_NOT_ALLOWED, ANONYMOUS_ID_REQUIRES_SITE, ANONYMOUS_ID_SITE_NOT_ALLOWED, CONTEXT_INVALID, CONTEXT_SITE_INVALID, EVENT_DATA_REQUIRED, EVENT_DATA_INVALID, EVENT_REFERENCE_PERSONAL, OPPORTUNITY_UNKNOWN, MONEY_REQUIRED, MONEY_INVALID, MONEY_FLOAT_NOT_ALLOWED, MONEY_PRECISION, MONEY_MISMATCH, MONEY_NEGATIVE, CURRENCY_INVALID, CURRENCY_EXPONENT_UNSUPPORTED, EVENT_PAYLOAD_CREDENTIAL, EVENT_PAYLOAD_TOO_LARGE…", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "503": { "description": "INGEST_PAUSED: intake stopped by the platform; retry with the same eventId.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "eventId", "eventType", "occurredAt", "subject", "data" ], "properties": { "eventId": { "type": "string", "description": "Your stable ID of this fact (retries reuse it). Unique per source.", "minLength": 1, "maxLength": 160, "pattern": "^[\\x21-\\x7E]+$" }, "eventType": { "type": "string", "enum": [ "conversion.reported", "order.paid", "order.refunded", "custom" ], "description": "Only the types allowed in your source." }, "schemaVersion": { "type": "integer", "enum": [ 1 ], "default": 1 }, "occurredAt": { "type": "string", "description": "When it happened, RFC 3339 in UTC (Z or +00:00); at most 5 minutes ahead and 30 days old.", "format": "date-time", "examples": [ "2026-09-28T10:15:30Z" ] }, "subject": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "contactId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "RouterClip contact ID (a merged ID resolves to the kept contact)." }, "externalId": { "type": "string", "description": "Your customer ID linked to a contact for this source; never an email or phone.", "minLength": 1, "maxLength": 128 }, "anonymousId": { "type": "string", "description": "Visitor ID from aiocrm.js getVisitorId; conversions and orders only, with context.site. It identifies a contact only when your company links visitors (marketing.identity) and the browser was linked with ['identify', token] before occurredAt; then context.site must be allowed in your source.", "format": "uuid" } }, "description": "At least one identity; all of them must identify the same contact." }, "context": { "type": "object", "additionalProperties": false, "properties": { "site": { "type": "string", "description": "Public ID of an active verified website of your company.", "pattern": "^st_[A-Za-z0-9_-]{24}$" } }, "description": "Only site. Attribution tokens are never accepted." }, "data": { "oneOf": [ { "title": "conversion.reported", "type": "object", "additionalProperties": false, "required": [ "conversionId", "conversionType" ], "properties": { "conversionId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your ID of the conversion." }, "conversionType": { "type": "string", "pattern": "^[a-z0-9_.]{1,48}$", "description": "Kind of conversion, e.g. lead, demo_request." }, "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Order it belongs to, if any." }, "opportunityId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "RouterClip opportunity it refers to (it is never marked as won by this event)." }, "amount": { "type": "string", "description": "Decimal string with at most the currency's decimals (up to three), e.g. \"129.90\". Never a JSON number with decimals.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "129.90" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Integer amount in minor units (ISO 4217 exponent): 12990 EUR = 129.90." }, "currency": { "type": "string", "description": "ISO 4217 code with zero to three decimals.", "pattern": "^[A-Za-z]{3}$", "examples": [ "EUR" ] } }, "description": "Amount and currency go together and are optional." }, { "title": "order.paid", "type": "object", "additionalProperties": false, "required": [ "orderId", "paymentId", "currency" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your order ID." }, "paymentId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your payment ID; an order can have several." }, "amount": { "type": "string", "description": "Decimal string with at most the currency's decimals (up to three), e.g. \"129.90\". Never a JSON number with decimals.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "129.90" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Integer amount in minor units (ISO 4217 exponent): 12990 EUR = 129.90." }, "currency": { "type": "string", "description": "ISO 4217 code with zero to three decimals.", "pattern": "^[A-Za-z]{3}$", "examples": [ "EUR" ] } }, "description": "A declared purchase (clientDeclared), never a verified payment. Send amount or amountMinor." }, { "title": "order.refunded", "type": "object", "additionalProperties": false, "required": [ "orderId", "refundId", "currency", "full" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$" }, "paymentId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$" }, "refundId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your refund ID." }, "full": { "type": "boolean", "description": "Whether the order is now fully refunded." }, "amount": { "type": "string", "description": "Decimal string with at most the currency's decimals (up to three), e.g. \"129.90\". Never a JSON number with decimals.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "129.90" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Integer amount in minor units (ISO 4217 exponent): 12990 EUR = 129.90." }, "currency": { "type": "string", "description": "ISO 4217 code with zero to three decimals.", "pattern": "^[A-Za-z]{3}$", "examples": [ "EUR" ] } }, "description": "The amount of this refund (greater than zero), not a running total." }, { "title": "custom", "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_.]{1,48}$", "description": "Name of your custom event." }, "properties": { "type": "object", "maxProperties": 30, "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,47}$" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "maxItems": 20, "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] }, "description": "Flat properties; names with credential markers (token, secret…) are rejected and amount/currency are read as money." } }, "description": "Needs a contact linked to your source." } ], "description": "Closed schema of eventType: unknown fields are rejected." } } }, "examples": { "orderPaid": { "summary": "Declared order paid, customer linked by externalId", "value": { "eventId": "erp-order-842-paid-v1", "eventType": "order.paid", "schemaVersion": 1, "occurredAt": "2026-09-28T10:15:30Z", "subject": { "externalId": "customer_872" }, "data": { "orderId": "order_842", "paymentId": "payment_603", "amountMinor": 12990, "currency": "EUR" } } }, "conversionFromSite": { "summary": "Conversion of a visitor of a verified website", "value": { "eventId": "checkout_ORDER-42_lead", "eventType": "conversion.reported", "occurredAt": "2026-09-28T10:20:00Z", "subject": { "anonymousId": "5f0c2a9e-3b7d-4c1a-9e55-0d7c1b2a6f10" }, "data": { "conversionId": "lead-42", "conversionType": "demo_request" }, "context": { "site": "st_AbCdEfGhIjKlMnOpQrStUvWx" } } }, "custom": { "summary": "Custom event of a linked contact", "value": { "eventId": "app-login-2026-09-28-872", "eventType": "custom", "occurredAt": "2026-09-28T09:00:00Z", "subject": { "externalId": "customer_872" }, "data": { "name": "app.login", "properties": { "plan": "pro", "seats": 3 } } } } } } } } } }, "/api/v1/events/import": { "post": { "tags": [ "Events" ], "summary": "Import historical events", "description": "Up to 500 past events per request (scope `events:import`), stored with `mode` `import`: they never\nenroll, wake waits, attribute or send. One result per element (`accepted`, `duplicate` or `rejected` with\nits code); an `eventId` already received live is a `duplicate`.", "operationId": "importEvents", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Every element was processed: accepted (stored with mode import, without deliveries), duplicate (already received, no cost) or rejected with its code. Retry-After is present when the daily import quota rejected some elements.", "content": { "application/json": { "schema": { "type": "object", "required": [ "mode", "received", "accepted", "duplicates", "rejected", "results" ], "properties": { "mode": { "type": "string", "enum": [ "import" ] }, "received": { "type": "integer" }, "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "rejected": { "type": "integer" }, "retention": { "type": "object", "properties": { "months": { "type": "integer" }, "oldestOccurredAt": { "type": "string", "format": "date-time" } } }, "dailyQuota": { "type": "object", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" } }, "description": "Imported events of the company today (UTC), apart from the live quota." }, "results": { "type": "array", "items": { "type": "object", "required": [ "index", "status" ], "properties": { "index": { "type": "integer", "description": "Position of the element in events." }, "eventId": { "type": [ "string", "null" ], "description": "Your eventId (null when it was not valid)." }, "status": { "type": "string", "enum": [ "accepted", "duplicate", "rejected" ] }, "id": { "type": "string", "description": "RouterClip event ID: the new event (accepted), the one already received (duplicate) or the conflicting one (IDEMPOTENCY_CONFLICT)." }, "eventType": { "type": "string", "enum": [ "conversion.reported", "order.paid", "order.refunded", "custom" ] }, "occurredAt": { "type": "string", "format": "date-time" }, "mode": { "type": "string", "enum": [ "live", "import" ], "description": "How the stored event was received." }, "contactResolved": { "type": "boolean" }, "statusUrl": { "type": "string", "description": "Receipt URL (readable with events:read)." }, "code": { "type": "string", "description": "Rejected: the UPPER_CASE code POST /api/v1/events would answer, or EVENT_OCCURRED_OUT_OF_RETENTION, RATE_LIMITED (quota companyImportsPerDay)." }, "message": { "type": "string" }, "httpStatus": { "type": "integer", "description": "The status the live route would answer (403, 409, 422, 429)." }, "field": { "type": "string", "description": "Path of the rejected field inside the event; values are never repeated." } } }, "description": "One result per element, in order." } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (events:import; events:write is not enough) or FEATURE_DISABLED (marketing.api).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 1 MiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "Invalid batch: IMPORT_BODY_INVALID, IMPORT_FIELD_NOT_ALLOWED, IMPORT_EVENTS_REQUIRED, IMPORT_TOO_MANY_EVENTS (more than 500 events), IDEMPOTENCY_KEY_NOT_SUPPORTED. Invalid events are rejected one by one in the 200 answer.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Per-minute quota of the key or the company (RATE_LIMITED) or API_AUTH_THROTTLED; nothing was written.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "503": { "description": "INGEST_PAUSED: intake stopped by the platform; retry the same batch later.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "type": "object", "additionalProperties": false, "required": [ "eventId", "eventType", "occurredAt", "subject", "data" ], "properties": { "eventId": { "type": "string", "description": "Your stable ID of this fact (retries reuse it). Unique per source.", "minLength": 1, "maxLength": 160, "pattern": "^[\\x21-\\x7E]+$" }, "eventType": { "type": "string", "enum": [ "conversion.reported", "order.paid", "order.refunded", "custom" ], "description": "Only the types allowed in your source." }, "schemaVersion": { "type": "integer", "enum": [ 1 ], "default": 1 }, "occurredAt": { "type": "string", "format": "date-time", "examples": [ "2026-03-02T09:30:00Z" ], "description": "When it happened, RFC 3339 in UTC (Z or +00:00): inside your company's data retention and at most 5 minutes ahead (EVENT_OCCURRED_OUT_OF_RETENTION, EVENT_OCCURRED_IN_FUTURE)." }, "subject": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "contactId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "RouterClip contact ID (a merged ID resolves to the kept contact)." }, "externalId": { "type": "string", "description": "Your customer ID linked to a contact for this source; never an email or phone.", "minLength": 1, "maxLength": 128 }, "anonymousId": { "type": "string", "description": "Visitor ID from aiocrm.js getVisitorId; conversions and orders only, with context.site. It identifies a contact only when your company links visitors (marketing.identity) and the browser was linked with ['identify', token] before occurredAt; then context.site must be allowed in your source.", "format": "uuid" } }, "description": "At least one identity; all of them must identify the same contact." }, "context": { "type": "object", "additionalProperties": false, "properties": { "site": { "type": "string", "description": "Public ID of an active verified website of your company.", "pattern": "^st_[A-Za-z0-9_-]{24}$" } }, "description": "Only site. Attribution tokens are never accepted." }, "data": { "oneOf": [ { "title": "conversion.reported", "type": "object", "additionalProperties": false, "required": [ "conversionId", "conversionType" ], "properties": { "conversionId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your ID of the conversion." }, "conversionType": { "type": "string", "pattern": "^[a-z0-9_.]{1,48}$", "description": "Kind of conversion, e.g. lead, demo_request." }, "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Order it belongs to, if any." }, "opportunityId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "RouterClip opportunity it refers to (it is never marked as won by this event)." }, "amount": { "type": "string", "description": "Decimal string with at most the currency's decimals (up to three), e.g. \"129.90\". Never a JSON number with decimals.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "129.90" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Integer amount in minor units (ISO 4217 exponent): 12990 EUR = 129.90." }, "currency": { "type": "string", "description": "ISO 4217 code with zero to three decimals.", "pattern": "^[A-Za-z]{3}$", "examples": [ "EUR" ] } }, "description": "Amount and currency go together and are optional." }, { "title": "order.paid", "type": "object", "additionalProperties": false, "required": [ "orderId", "paymentId", "currency" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your order ID." }, "paymentId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your payment ID; an order can have several." }, "amount": { "type": "string", "description": "Decimal string with at most the currency's decimals (up to three), e.g. \"129.90\". Never a JSON number with decimals.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "129.90" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Integer amount in minor units (ISO 4217 exponent): 12990 EUR = 129.90." }, "currency": { "type": "string", "description": "ISO 4217 code with zero to three decimals.", "pattern": "^[A-Za-z]{3}$", "examples": [ "EUR" ] } }, "description": "A declared purchase (clientDeclared), never a verified payment. Send amount or amountMinor." }, { "title": "order.refunded", "type": "object", "additionalProperties": false, "required": [ "orderId", "refundId", "currency", "full" ], "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$" }, "paymentId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$" }, "refundId": { "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[\\x21-\\x7E]+$", "description": "Your refund ID." }, "full": { "type": "boolean", "description": "Whether the order is now fully refunded." }, "amount": { "type": "string", "description": "Decimal string with at most the currency's decimals (up to three), e.g. \"129.90\". Never a JSON number with decimals.", "pattern": "^[0-9]+(\\.[0-9]+)?$", "examples": [ "129.90" ] }, "amountMinor": { "type": "integer", "minimum": 0, "description": "Integer amount in minor units (ISO 4217 exponent): 12990 EUR = 129.90." }, "currency": { "type": "string", "description": "ISO 4217 code with zero to three decimals.", "pattern": "^[A-Za-z]{3}$", "examples": [ "EUR" ] } }, "description": "The amount of this refund (greater than zero), not a running total." }, { "title": "custom", "type": "object", "additionalProperties": false, "required": [ "name" ], "properties": { "name": { "type": "string", "pattern": "^[a-z0-9_.]{1,48}$", "description": "Name of your custom event." }, "properties": { "type": "object", "maxProperties": 30, "propertyNames": { "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,47}$" }, "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "maxItems": 20, "items": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ] }, "description": "Flat properties; names with credential markers (token, secret…) are rejected and amount/currency are read as money." } }, "description": "Needs a contact linked to your source." } ], "description": "Closed schema of eventType: unknown fields are rejected." } } }, "description": "1-500 events with the contract of POST /api/v1/events (whole body at most 1 MiB). They are stored with mode import: no journey, wait, attribution or send." } } }, "examples": { "history": { "summary": "Past orders and a refund of linked customers", "value": { "events": [ { "eventId": "erp-order-512-paid-v1", "eventType": "order.paid", "occurredAt": "2026-03-02T09:30:00Z", "subject": { "externalId": "customer_872" }, "data": { "orderId": "order_512", "paymentId": "payment_377", "amountMinor": 4990, "currency": "EUR" } }, { "eventId": "erp-order-512-refund-1", "eventType": "order.refunded", "occurredAt": "2026-03-10T16:00:00Z", "subject": { "externalId": "customer_872" }, "data": { "orderId": "order_512", "refundId": "refund_12", "amount": "49.90", "currency": "EUR", "full": true } }, { "eventId": "app-signup-2026-01-15-872", "eventType": "custom", "occurredAt": "2026-01-15T08:00:00Z", "subject": { "externalId": "customer_872" }, "data": { "name": "app.signup", "properties": { "plan": "pro" } } } ] } } } } } } } }, "/api/v1/events/{event_id}": { "get": { "tags": [ "Events" ], "summary": "Read an event receipt", "description": "The receipt of an event of the key's own source (scope `events:read` or `events:write`).", "operationId": "getEventReceipt", "parameters": [ { "name": "event_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Event Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The receipt: normalization and the status of each consumer's delivery, without payload.", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "eventId", "eventType", "status", "receivedAt", "trust", "mode", "deliveries", "statusUrl" ], "properties": { "id": { "type": "string", "description": "RouterClip event ID (use it to read the receipt)." }, "eventId": { "type": "string", "description": "Your eventId." }, "eventType": { "type": "string", "enum": [ "conversion.reported", "order.paid", "order.refunded", "custom" ] }, "schemaVersion": { "type": "integer" }, "status": { "type": "string", "enum": [ "accepted" ], "description": "Durable reception; not an action completed." }, "duplicate": { "type": "boolean", "description": "Only in POST answers: true when the same event had already been accepted." }, "occurredAt": { "type": "string", "format": "date-time" }, "receivedAt": { "type": "string", "format": "date-time" }, "trust": { "type": "string", "enum": [ "clientDeclared" ] }, "mode": { "type": "string", "enum": [ "live", "import" ], "description": "live for POST /api/v1/events; import for events loaded with POST /api/v1/events/import." }, "contactResolved": { "type": "boolean" }, "normalization": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "normalized" ] }, "money": { "type": [ "object", "null" ], "properties": { "amount": { "type": "string" }, "amountMinor": { "type": "integer" }, "exponent": { "type": "integer" }, "currency": { "type": "string" } } } } }, "attribution": { "type": [ "object", "null" ], "properties": { "basis": { "type": "string", "enum": [ "browser", "contact", "none" ] }, "site": { "type": [ "string", "null" ] } }, "description": "What attribution can use (conversions and orders); the decision is the delivery of marketing.attribution." }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "consumer": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "processing", "done", "failed", "skipped" ] }, "attempts": { "type": "integer" }, "lastError": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "description": "One receipt per consumer, without payload. done does not mean a message was delivered." }, "statusUrl": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (events:read or events:write) or FEATURE_DISABLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "EVENT_NOT_FOUND: not an event of the key's source.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/form-placements": { "get": { "tags": [ "Forms" ], "summary": "List form placements", "description": "Popup and inline placements of hosted forms with their task and actions (scope `forms:read`; feature\n`marketing.pages`); never the install snippet.", "operationId": "listFormPlacements", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated placement statuses (draft, active, paused, archived).", "examples": [ "active,paused" ], "title": "Status" }, "description": "Comma separated placement statuses (draft, active, paused, archived)." }, { "name": "siteId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the placements of this website.", "title": "Siteid" }, "description": "Only the placements of this website." }, { "name": "formId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the placements of this form.", "title": "Formid" }, "description": "Only the placements of this form." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Placements of the company, archived last and newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFormPlacementPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (forms:read) or FEATURE_DISABLED (api.tasks or marketing.pages).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/form-placements/{placement_id}": { "get": { "tags": [ "Forms" ], "summary": "Read a form placement", "description": "A placement with its rules, blockers, task, actions and `ETag` (scope `forms:read`).", "operationId": "getFormPlacement", "parameters": [ { "name": "placement_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Placement Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The placement with its rules, blockers, task, actions and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiFormPlacement" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the placement; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (forms:read) or FEATURE_DISABLED (api.tasks or marketing.pages).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PLACEMENT_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/form-placements/{resource_id}/actions/{action}": { "post": { "tags": [ "Forms" ], "summary": "Run an action of a form placement", "description": "Run an action of a form-placements resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runFormPlacementAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "activate": { "summary": "Activate (form_placement.activate; forms:admin, delegated)", "value": { "input": {} } }, "pause": { "summary": "Pause (form_placement.pause; forms:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/forms": { "get": { "tags": [ "Forms" ], "summary": "List signup forms", "description": "Signup forms and their hosted pages with their task and actions (scope `forms:read`; feature `marketing.pages`).", "operationId": "listForms", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated form statuses (draft, published, paused, archived).", "examples": [ "draft,paused" ], "title": "Status" }, "description": "Comma separated form statuses (draft, published, paused, archived)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Signup forms, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSignupFormPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (forms:read) or FEATURE_DISABLED (api.tasks, or marketing.pages for hosted forms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/forms/{form_id}": { "get": { "tags": [ "Forms" ], "summary": "Read a signup form", "description": "A signup form with its state, published version, task, actions and `ETag` (scope `forms:read`).", "operationId": "getForm", "parameters": [ { "name": "form_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Form Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The form with its state, versions, task, actions and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSignupForm" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the form; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (forms:read) or FEATURE_DISABLED (api.tasks, or marketing.pages for hosted forms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "FORM_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/forms/{form_id}/actions/{action}": { "post": { "tags": [ "Forms" ], "summary": "Run an action of a signup form", "description": "publish, pause, resume or archive (`forms:admin`, delegated administrator; `expectedRevision` or `If-Match`): the\nsame checks, `dryRun` and idempotency as the task actions.", "operationId": "runFormAction", "parameters": [ { "name": "form_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Form Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "archive": { "summary": "Archive (signup_form.archive; forms:admin, delegated)", "value": { "input": {} } }, "resume": { "summary": "Resume (signup_form.resume; forms:admin, delegated)", "value": { "input": {} } }, "publish": { "summary": "Publish the draft you read (412 when it changed)", "value": { "input": { "expectedRevision": 3 } } }, "pause": { "summary": "Pause the published page", "value": { "input": {} } } } } } } } }, "/api/v1/forms/{form_id}/versions": { "get": { "tags": [ "Forms" ], "summary": "List the versions of a signup form", "description": "The published (immutable) versions of a form, newest first (scope `forms:read`).", "operationId": "listFormVersions", "parameters": [ { "name": "form_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Form Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The published versions of the form.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSignupFormVersions" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (forms:read) or FEATURE_DISABLED (api.tasks, or marketing.pages for hosted forms).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "FORM_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/identity/link-tokens": { "post": { "tags": [ "Identity" ], "summary": "Issue a one-time identity link token", "description": "A token that your page passes to `aiocrm.js` so RouterClip links that browser (visitor or push subscription)\nwith the contact (scope `identity:link`, feature `marketing.identity` and its confirmed legal basis). Valid\n5 minutes, one use per purpose, only on the website you name, which must be allowed in the source.", "operationId": "createIdentityLinkToken", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "A new token, valid 5 minutes, one use per purpose. Only its SHA-256 is stored; the answer has Cache-Control: no-store.", "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "tokenType", "expiresAt", "expiresIn", "site", "purposes", "shownOnce" ], "properties": { "token": { "type": "string", "description": "ilt_… Hand it to the page (never in a URL); aiocrm.js sends it in a body." }, "tokenType": { "type": "string", "enum": [ "identity_link" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "expiresIn": { "type": "integer", "description": "Seconds of validity (300)." }, "site": { "type": "string" }, "purposes": { "type": "array", "items": { "type": "string", "enum": [ "push", "anonymous", "push_manage" ] } }, "shownOnce": { "type": "boolean", "description": "Only its hash is stored: it cannot be shown again." } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (identity:link), FEATURE_DISABLED (marketing.api or marketing.identity), LEGAL_BASIS_REQUIRED (the company has not confirmed the legal basis of marketing.identity) or SITE_NOT_ALLOWED (the website is not an active, verified website of the company allowed in the source).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "CONTACT_NOT_FOUND: no contact the source reaches has this externalId or contactId.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "409": { "description": "CONTACT_OPTED_OUT: purpose anonymous for a contact that objected to profiling.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "LINK_TOKEN_BODY_INVALID, LINK_TOKEN_FIELD_UNKNOWN, SUBJECT_REQUIRED, SUBJECT_INVALID, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE, SITE_REQUIRED, SITE_INVALID or PURPOSES_INVALID.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject", "site", "purposes" ], "properties": { "subject": { "type": "object", "additionalProperties": false, "minProperties": 1, "maxProperties": 1, "description": "Exactly one: the externalId of your source or a contactId your source reaches. A merged record gives the token of the kept one.", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128 }, "contactId": { "type": "string", "minLength": 1, "maxLength": 64 } } }, "site": { "type": "string", "pattern": "^st_[A-Za-z0-9_-]{24}$", "description": "publicId of an active, verified website of the company allowed in the source." }, "purposes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "push", "anonymous", "push_manage" ] }, "description": "push: link the browser's push subscription; anonymous: link the visitor of the tracker (needs analytics consent in the browser); push_manage: let the browser change the contact's push preferences. Each purpose can be used once." } } }, "examples": { "pushAndPreferences": { "summary": "Signed-in customer: link push and let the page manage its preferences", "value": { "subject": { "externalId": "customer_872" }, "site": "st_AbCdEfGhIjKlMnOpQrStUvWx", "purposes": [ "push", "push_manage" ] } }, "visitor": { "summary": "Link the tracked visitor of the website", "value": { "subject": { "externalId": "customer_872" }, "site": "st_AbCdEfGhIjKlMnOpQrStUvWx", "purposes": [ "anonymous" ] } } } } } } } }, "/api/v1/journey-enrollments/{resource_id}/actions/{action}": { "post": { "tags": [ "Journeys" ], "summary": "Run an action of an enrollment", "description": "Run an action of a journey-enrollments resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runJourneyEnrollmentAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "cancel": { "summary": "Cancel the enrollment (journey_enrollment.cancel; journeys:admin, delegated)", "value": { "input": {} } }, "pause": { "summary": "Pause the enrollment (journey_enrollment.pause; journeys:admin, delegated)", "value": { "input": {} } }, "resume": { "summary": "Resume the enrollment (journey_enrollment.resume; journeys:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/key": { "get": { "tags": [ "Key" ], "summary": "Current Key", "description": "The key in use, its source and scopes: lets an integrator check its setup without side effects.", "operationId": "current_key_api_v1_key_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Current Key Api V1 Key Get" } } } } } } }, "/api/v1/key/capabilities": { "get": { "tags": [ "Key" ], "summary": "What this key can see and do", "description": "Areas and kinds visible to the key, enabled features, delegable users (ID and name), the default user and the\nrelevant send switches (any scope; feature `api.tasks`).", "operationId": "getKeyCapabilities", "responses": { "200": { "description": "What the key can see and do now: visible areas, features, delegable users, default user and send switches. No secret, email or bearer link.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "keyId": { "type": "string" }, "source": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "scopes": { "items": { "type": "string" }, "type": "array", "description": "Scopes of this key." }, "areas": { "items": { "properties": { "area": { "type": "string", "enum": [ "contacts", "companies", "deals", "activities", "sequences", "playbooks", "duplicates", "support", "csat", "voice", "calendar", "campaigns", "journeys", "segments", "forms", "sites", "conversions", "knowledge", "channels", "reports", "team", "webhooks", "automation" ] }, "name": { "properties": { "es": { "type": "string" }, "en": { "type": "string" } }, "type": "object" }, "scopes": { "items": { "type": "string" }, "type": "array" }, "readable": { "type": "boolean", "description": "Its kinds can appear in the task feed." }, "feature": { "type": [ "string", "null" ], "description": "Feature the whole area needs besides api.tasks." }, "partialFeatures": { "items": { "properties": { "key": { "type": "string" }, "enabled": { "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array", "description": "Only the areas where the key has a scope and whose feature is on." }, "features": { "items": { "properties": { "key": { "type": "string" }, "enabled": { "type": "boolean" } }, "type": "object" }, "type": "array", "description": "api.tasks and the features the visible areas depend on." }, "actAs": { "properties": { "allowed": { "type": "boolean", "description": "The key has the act_as scope." }, "header": { "type": "string", "enum": [ "X-AIO-Act-As" ] }, "users": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "agent" ] } }, "type": "object", "required": [ "id", "name", "role" ] }, "type": "array", "description": "Delegable users (ID, name and role)." }, "defaultUserId": { "type": [ "string", "null" ], "description": "User who acts without the header; null when there is none or it can no longer act." }, "defaultUserUnavailable": { "type": "boolean", "description": "A default user is configured but cannot act: service operations run as the source and those that need a person answer 403 DELEGATED_USER_INACTIVE; send X-AIO-Act-As or ask an administrator." } }, "type": "object" }, "switches": { "additionalProperties": { "type": "boolean" }, "type": "object", "description": "Global send switches that affect what this key can do (task webhooks and the visible areas)." }, "limits": { "properties": { "delegatesPerSource": { "type": "integer" } }, "type": "object" }, "kinds": { "items": {}, "type": "array", "description": "Task kinds visible to this key (filled by the task registry)." } }, "type": "object", "required": [ "keyId", "source", "scopes", "areas", "features", "actAs", "switches" ] } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } } } } }, "/api/v1/knowledge/documents": { "get": { "tags": [ "Knowledge" ], "summary": "List knowledge documents", "description": "Knowledge documents, newest first, with the task each one generates (scope `knowledge:read`); never the text.", "operationId": "listKnowledgeDocuments", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Knowledge documents, newest first, without their text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeDocumentPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (knowledge:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Knowledge" ], "summary": "Create a knowledge document", "description": "Add a document written by hand (scope `knowledge:admin`, delegated administrator; `Idempotency-Key` required).", "operationId": "createKnowledgeDocument", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created through the same function as the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeDocument" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new task.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (knowledge:admin), FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT (an administrator acts).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB, SOURCE_TOO_LARGE or KNOWLEDGE_STORAGE_QUOTA_EXCEEDED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, SOURCE_URL_NOT_PUBLIC (link: not HTTPS or not only public addresses), SOURCE_DOWNLOAD_FAILED, SOURCE_FORMAT_UNSUPPORTED or GOOGLE_DRIVE_RECONNECT_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "503": { "description": "KNOWLEDGE_INDEX_UNAVAILABLE: nothing was saved; retry later.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title", "content" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1 }, "language": { "type": "string", "enum": [ "es", "en" ], "default": "es" }, "agentTypes": { "type": "array", "maxItems": 6, "items": { "type": "string", "enum": [ "voice", "web", "whatsapp", "instagram", "messenger", "email" ] }, "description": "Assistants that may use the document; none by default." } } }, "examples": { "faq": { "summary": "A document written by hand", "value": { "title": "Horario de soporte", "content": "Atendemos de lunes a viernes de 9:00 a 18:00.", "language": "es", "agentTypes": [ "web", "email" ] } } } } } } } }, "/api/v1/knowledge/documents/link": { "post": { "tags": [ "Knowledge" ], "summary": "Import a knowledge document from a link", "description": "Import a public HTTPS page or a Google Drive file with the protections of the app (scope `knowledge:admin`,\ndelegated administrator; `Idempotency-Key` required). A link that is not HTTPS or does not resolve only to public\naddresses is `422 SOURCE_URL_NOT_PUBLIC`.", "operationId": "linkKnowledgeDocument", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created through the same function as the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeDocument" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new task.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (knowledge:admin), FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT (an administrator acts).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB, SOURCE_TOO_LARGE or KNOWLEDGE_STORAGE_QUOTA_EXCEEDED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, SOURCE_URL_NOT_PUBLIC (link: not HTTPS or not only public addresses), SOURCE_DOWNLOAD_FAILED, SOURCE_FORMAT_UNSUPPORTED or GOOGLE_DRIVE_RECONNECT_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "503": { "description": "KNOWLEDGE_INDEX_UNAVAILABLE: nothing was saved; retry later.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "url" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The page title by default." }, "url": { "type": "string", "minLength": 10, "maxLength": 4096, "description": "HTTPS on port 443 that resolves only to public addresses (or a Google Drive file link)." }, "language": { "type": "string", "enum": [ "es", "en" ], "default": "es" }, "agentTypes": { "type": "array", "maxItems": 6, "items": { "type": "string", "enum": [ "voice", "web", "whatsapp", "instagram", "messenger", "email" ] }, "description": "Assistants that may use the document; none by default." }, "refreshIntervalHours": { "type": "integer", "minimum": 1, "maximum": 8760, "default": 24 }, "googleConnectionId": { "type": "string", "description": "An authorized Google Drive connection of the company." } } }, "examples": { "page": { "summary": "A public page refreshed every day", "value": { "url": "https://www.example.com/ayuda/envios", "language": "es", "agentTypes": [ "web" ], "refreshIntervalHours": 24 } } } } } } } }, "/api/v1/knowledge/documents/{document_id}": { "get": { "tags": [ "Knowledge" ], "summary": "Read a knowledge document", "description": "A knowledge document with its `ETag` and the refresh action (scope `knowledge:read`); the text with\n`include=content`.", "operationId": "getKnowledgeDocument", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "content: also the text of the document.", "examples": [ "content" ], "title": "Include" }, "description": "content: also the text of the document." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "The document; its text only with include=content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeDocument" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (knowledge:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "KNOWLEDGE_DOCUMENT_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "patch": { "tags": [ "Knowledge" ], "summary": "Change a knowledge document", "description": "Change title, language, assistants, refresh interval or (documents written by hand) text (scope\n`knowledge:admin`, delegated administrator; `If-Match` required).", "operationId": "updateKnowledgeDocument", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source); another body is 409.", "title": "Idempotency-Key" }, "description": "1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source); another body is 409." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The document after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeDocument" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (knowledge:admin), FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT (an administrator acts).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "KNOWLEDGE_DOCUMENT_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header).", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB, SOURCE_TOO_LARGE or KNOWLEDGE_STORAGE_QUOTA_EXCEEDED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, CONTENT_NOT_EDITABLE (an imported document changes by refreshing its source) or IF_MATCH_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "503": { "description": "KNOWLEDGE_INDEX_UNAVAILABLE.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string", "minLength": 1, "description": "Only documents written by hand." }, "language": { "type": "string", "enum": [ "es", "en" ] }, "agentTypes": { "type": "array", "maxItems": 6, "items": { "type": "string", "enum": [ "voice", "web", "whatsapp", "instagram", "messenger", "email" ] }, "description": "Assistants that may use the document; none by default." }, "refreshIntervalHours": { "type": "integer", "minimum": 1, "maximum": 8760 } }, "description": "Only the fields sent change; null is not accepted." }, "examples": { "title": { "summary": "Rename a document", "value": { "title": "Política de devoluciones 2026" } } } } } } } }, "/api/v1/knowledge/documents/{document_id}/actions/{action}": { "post": { "tags": [ "Knowledge" ], "summary": "Run an action of a knowledge document", "description": "refresh (scope `knowledge:admin`, delegated administrator; `202`): the same checks, `dryRun` and idempotency as\nthe task action.", "operationId": "runKnowledgeDocumentAction", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "refresh": { "summary": "Refresh from the source (knowledge_document.refresh; knowledge:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/knowledge/storage": { "get": { "tags": [ "Knowledge" ], "summary": "Read the knowledge storage", "description": "Used and available knowledge storage of the company (scope `knowledge:read`).", "operationId": "getKnowledgeStorage", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Knowledge storage of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKnowledgeStorage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (knowledge:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/labels": { "get": { "tags": [ "Support" ], "summary": "List the support labels", "description": "The labels of the company (scope `support:read`).", "operationId": "listSupportLabels", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Labels of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSupportLabels" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/macros": { "get": { "tags": [ "Support" ], "summary": "List the support macros", "description": "The macros of the company (scope `support:read`).", "operationId": "listSupportMacros", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Macros of the company (apply them with the apply_macro action).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSupportMacros" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/mail-domains": { "get": { "tags": [ "Channels" ], "summary": "List mail domains", "description": "Hosted mail domains with their verification and task (scope `channels:read`).", "operationId": "listMailDomains", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Hosted mail domains of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMailDomainPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (channels:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/mail-domains/{domain_id}/dns": { "get": { "tags": [ "Channels" ], "summary": "Read the DNS records of a mail domain", "description": "The records to publish and the stored checks (scope `channels:read`); the ownership token is redacted.", "operationId": "getMailDomainDns", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "DNS records and checks; the ownership token is redacted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMailDomainDns" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (channels:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "MAIL_DOMAIN_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/mail-domains/{resource_id}/actions/{action}": { "post": { "tags": [ "Channels" ], "summary": "Run an action of a mail domain", "description": "Run an action of a mail-domains resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runMailDomainAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "verify": { "summary": "Verify with the provider (mail_domain.verify; channels:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/marketing-connections": { "get": { "tags": [ "Channels" ], "summary": "List marketing connections", "description": "Email and SMS marketing connections with their verification and task (scope `channels:read`); never\ncredentials.", "operationId": "listMarketingConnections", "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "email or sms.", "examples": [ "email" ], "title": "Channel" }, "description": "email or sms." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Email and SMS marketing connections without credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMarketingConnectionPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (channels:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/marketing-connections/{resource_id}/actions/{action}": { "post": { "tags": [ "Channels" ], "summary": "Run an action of a marketing connection", "description": "Run an action of a marketing-connections resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runMarketingConnectionAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "verify": { "summary": "Verify with the provider (marketing_connection.verify; channels:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/marketing-webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List marketing webhooks", "description": "Marketing webhooks with the URL masked, delivery counts and task (scope `webhooks:manage`).", "operationId": "listMarketingWebhooks", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "Marketing webhooks with the URL masked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMarketingWebhookPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/marketing-webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List the deliveries of a marketing webhook", "description": "Status, attempts and last answer of each delivery, newest first (scope `webhooks:manage`); never the body.", "operationId": "listMarketingWebhookDeliveries", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Deliveries of a marketing webhook, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMarketingWebhookDeliveryPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/marketing-webhooks/{webhook_id}/deliveries/{delivery_id}/actions/{action}": { "post": { "tags": [ "Webhooks" ], "summary": "Run an action of a marketing webhook delivery", "description": "retry (scope `webhooks:manage`, delegated administrator; `202`): queue a failed delivery again, as the app.", "operationId": "runMarketingWebhookDeliveryAction", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Delivery Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "retry": { "summary": "Retry the delivery (marketing_webhook_delivery.retry; webhooks:manage, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/members": { "get": { "tags": [ "Team" ], "summary": "List the team members", "description": "Active administrators and agents with `id`, `name` and `role` to map assignees (scope `team:read`); `email` only\nwith `team:emails`.", "operationId": "listMembers", "responses": { "200": { "description": "Active administrators and agents of the company: id, name and role (email only with team:emails).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "agent" ] }, "email": { "type": "string", "description": "Only with the team:emails scope." } }, "type": "object", "required": [ "id", "name", "role" ] }, "type": "array" }, "emailsIncluded": { "type": "boolean" } }, "type": "object", "required": [ "items", "emailsIncluded" ] } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } }, "403": { "description": "API_SCOPE_REQUIRED (team:read) or FEATURE_DISABLED (api.tasks).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ] } } } } } } }, "/api/v1/members/{user_id}/availability": { "put": { "tags": [ "Support" ], "summary": "Change the support availability of a member", "description": "Online, away or offline in the support queue (scope `support:write`): the delegated user's own availability, or\nanybody's when the delegated user is an administrator.", "operationId": "setMemberAvailability", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The availability after the change, through the same function as the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMemberAvailability" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:write), FEATURE_DISABLED (api.tasks), DELEGATED_USER_REQUIRED (send X-AIO-Act-As or set a default user), DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT (an agent changes only their own availability; capacity needs an administrator).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "MEMBER_NOT_FOUND: not an active administrator or agent of the company (the same answer for another company).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED or VALIDATION_ERROR (availability online, away or offline; capacity 1-100).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "availability" ], "properties": { "availability": { "type": "string", "enum": [ "online", "away", "offline" ] }, "capacity": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Conversations at once; only an administrator changes it." } } }, "examples": { "away": { "summary": "Away from the queue", "value": { "availability": "away" } } } } } } } }, "/api/v1/mentions": { "get": { "tags": [ "Support" ], "summary": "List the mentions of the delegated user", "description": "The mentions and notices of the delegated user (scope `support:read`); subjects and previews only with\n`support:content`. Mark one as read with `POST /api/v1/mentions/{id}/actions/mark_read`.", "operationId": "listMentions", "parameters": [ { "name": "unreadOnly", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: only unread mentions.", "examples": [ "true" ], "title": "Unreadonly" }, "description": "true: only unread mentions." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Mentions of the delegated user: unread first, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMentionPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_REQUIRED (send X-AIO-Act-As or set a default user), DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or ACTOR_ROLE_INSUFFICIENT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (unreadOnly, limit).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/mentions/{resource_id}/actions/{action}": { "post": { "tags": [ "Support" ], "summary": "Run an action of a mention", "description": "Run an action of a mentions resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runMentionAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "mark_read": { "summary": "Mark as read (support_mention.mark_read; support:execute, recipient)", "value": { "input": {} } } } } } } } }, "/api/v1/merges": { "get": { "tags": [ "Duplicates" ], "summary": "List merges", "description": "Merge operations of the company (scope `duplicates:read`): newest first by cursor or, with `recordId`, the\nmerges in which a record was kept or absorbed.", "operationId": "listMerges", "parameters": [ { "name": "entity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "contact (default) or company.", "examples": [ "contact" ], "title": "Entity" }, "description": "contact (default) or company." }, { "name": "recordId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the pairs or merges of this record (an ID, never personal data).", "title": "Recordid" }, "description": "Only the pairs or merges of this record (an ID, never personal data)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "completed or undone.", "title": "Status" }, "description": "completed or undone." }, { "name": "reviewPending", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: merges awaiting their review.", "examples": [ "true" ], "title": "Reviewpending" }, "description": "true: merges awaiting their review." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Merge operations (newest first) or the merges of one record, with taskIds.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMergePage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (duplicates:read) or FEATURE_DISABLED (api.tasks or crm.merge).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "RESOURCE_NOT_FOUND: recordId is not a record of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/merges/{merge_id}": { "get": { "tags": [ "Duplicates" ], "summary": "Read a merge", "description": "One merge operation with its `ETag` (scope `duplicates:read`): counts, provenance, review and undo\navailability; never the previous values of the records.", "operationId": "getMerge", "parameters": [ { "name": "merge_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Merge Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The operation: counts, provenance of every change (never previous values), review and undo availability.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMergeOperation" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the operation; send it back as If-Match of its actions.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (duplicates:read) or FEATURE_DISABLED (api.tasks or crm.merge).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "RESOURCE_NOT_FOUND: it does not exist or belongs to another company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/merges/{resource_id}/actions/{action}": { "post": { "tags": [ "Duplicates" ], "summary": "Run an action of a merge", "description": "Run an action of a merges resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runMergeAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "review": { "summary": "Mark as reviewed (merge_operation.review; duplicates:admin, delegated)", "value": { "input": {} } }, "undo": { "summary": "Undo the merge (merge_operation.undo; duplicates:admin, delegated)", "value": { "input": { "planHash": "9ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d79ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d7", "expiresAt": "2026-10-01T09:00:00Z" } } }, "undo.dryRun": { "summary": "Undo the merge: dryRun returns the confirmation token(s) planHash, expiresAt", "value": { "dryRun": true, "input": {} } } } } } } } }, "/api/v1/notification-jobs/{resource_id}/actions/{action}": { "post": { "tags": [ "Support" ], "summary": "Review a team alert", "description": "Run an action of a notification-jobs resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runNotificationJobAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "review": { "summary": "Review an unconfirmed alert (notification_job.review; support:admin, delegated)", "value": { "input": { "action": "confirm_delivered" } } } } } } } } }, "/api/v1/page-domains": { "get": { "tags": [ "Sites" ], "summary": "List custom page domains", "description": "The custom domains of the hosted pages with their task, never the verification token (scope `sites:read`;\nfeatures `marketing.pages` and `marketing.custom_domains`).", "operationId": "listPageDomains", "parameters": [ { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Custom domains of the company, without tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPageDomainPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sites:read) or FEATURE_DISABLED (api.tasks, marketing.pages or marketing.custom_domains).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PAGE_DOMAINS_UNAVAILABLE: custom domains are not enabled on this server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/page-domains/{domain_id}": { "get": { "tags": [ "Sites" ], "summary": "Read a custom page domain", "description": "A custom domain with its DNS checks, task, actions and `ETag`; never the token (scope `sites:read`).", "operationId": "getPageDomain", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Domain Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The domain with its DNS checks, task, actions and ETag; never the token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPageDomain" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" of the domain; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sites:read) or FEATURE_DISABLED (api.tasks, marketing.pages or marketing.custom_domains).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PAGE_DOMAIN_NOT_FOUND (it does not exist or belongs to another company, the same answer) or PAGE_DOMAINS_UNAVAILABLE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/page-domains/{resource_id}/actions/{action}": { "post": { "tags": [ "Sites" ], "summary": "Run an action of a custom page domain", "description": "Run an action of a page-domains resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runPageDomainAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "verify": { "summary": "Verify (page_domain.verify; sites:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/pipelines": { "get": { "tags": [ "Deals" ], "summary": "List the sales pipelines", "description": "Sales pipelines with their stages, outcomes and warning settings (scope `deals:read`; read only).", "operationId": "listPipelines", "parameters": [ { "name": "includeArchived", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: archived pipelines too.", "examples": [ "false" ], "title": "Includearchived" }, "description": "true: archived pipelines too." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Sales pipelines with their stages and outcomes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPipelines" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (deals:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (includeArchived).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/playbook-sessions": { "get": { "tags": [ "Playbooks" ], "summary": "List playbook sessions", "description": "Playbook sessions newest first with a cursor (scope `playbooks:read`); only IDs go in the URL.", "operationId": "listPlaybookSessions", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "draft, completed, abandoned or all (default).", "examples": [ "draft" ], "title": "State" }, "description": "draft, completed, abandoned or all (default)." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sessions of this contact (an absorbed contact's sessions count for its kept record).", "title": "Contactid" }, "description": "Sessions of this contact (an absorbed contact's sessions count for its kept record)." }, { "name": "dealId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sessions of this deal.", "title": "Dealid" }, "description": "Sessions of this deal." }, { "name": "activityId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sessions opened from this follow-up.", "title": "Activityid" }, "description": "Sessions opened from this follow-up." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sessions opened by this user.", "title": "Ownerid" }, "description": "Sessions opened by this user." }, { "name": "playbookId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sessions of this playbook.", "title": "Playbookid" }, "description": "Sessions of this playbook." }, { "name": "versionId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Sessions pinned to this version.", "title": "Versionid" }, "description": "Sessions pinned to this version." }, { "name": "startedFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: started at or after it.", "title": "Startedfrom" }, "description": "RFC 3339: started at or after it." }, { "name": "startedTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: started at or before it.", "title": "Startedto" }, "description": "RFC 3339: started at or before it." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Playbook sessions of the company, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlaybookSessionPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (playbooks:read) or FEATURE_DISABLED (api.tasks or crm.playbooks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Playbooks" ], "summary": "Open a playbook session", "description": "Open a session of a published playbook through the same function as the UI (scope `playbooks:write`, a delegated\nuser who becomes its owner; `Idempotency-Key` required).", "operationId": "openPlaybookSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Opened through the same function as the UI; the delegated user is its owner.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlaybookSession" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\"; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new session (/api/v1/playbook-sessions/{id}).", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (playbooks:write), FEATURE_DISABLED (api.tasks or crm.playbooks), DELEGATED_USER_REQUIRED (send X-AIO-Act-As or set a default user), DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PLAYBOOK_NOT_FOUND, PLAYBOOK_VERSION_NOT_FOUND, CONTACT_NOT_FOUND, OPPORTUNITY_NOT_FOUND, ACTIVITY_NOT_FOUND or CUSTOMER_COMPANY_NOT_FOUND (another company's records answer the same).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "PLAYBOOK_NOT_PUBLISHED, PLAYBOOK_ARCHIVED, PLAYBOOK_VERSION_SUPERSEDED (currentVersionId), MERGED_RECORD (canonicalId), OPPORTUNITY_ARCHIVED, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, PLAYBOOK_CONTACT_REQUIRED or PLAYBOOK_CONTEXT_MISMATCH (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "playbookId (its current published version) or versionId; the context must be coherent: a follow-up gives its contact and deal, a deal its contact.", "properties": { "playbookId": { "type": [ "string", "null" ], "maxLength": 64 }, "versionId": { "type": [ "string", "null" ], "maxLength": 64 }, "contactId": { "type": [ "string", "null" ], "maxLength": 64 }, "dealId": { "type": [ "string", "null" ], "maxLength": 64 }, "activityId": { "type": [ "string", "null" ], "maxLength": 64 }, "companyId": { "type": [ "string", "null" ], "maxLength": 64, "description": "A customer company of the contact." } } }, "examples": { "fromActivity": { "summary": "Open a playbook for a follow-up (its contact and deal come with it)", "value": { "playbookId": "6b1f2a9e-0000-4000-8000-000000000000", "activityId": "5f2c2a9e-0000-4000-8000-000000000000" } } } } } } } }, "/api/v1/playbook-sessions/{resource_id}/actions/{action}": { "post": { "tags": [ "Playbooks" ], "summary": "Run an action of a playbook session", "description": "Run an action of a playbook-sessions resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runPlaybookSessionAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "abandon": { "summary": "Abandon the session (playbook_session.abandon; playbooks:execute, delegated)", "value": { "input": {} } }, "complete": { "summary": "Complete the playbook (playbook_session.complete; playbooks:execute, delegated)", "value": { "input": { "expectedValues": [ { "entity": "contact", "fieldId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } ], "target": { "contactId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } } }, "complete.dryRun": { "summary": "Complete the playbook: dryRun returns the confirmation token(s) expectedValues, target", "value": { "dryRun": true, "input": {} } }, "save": { "summary": "Save answers (playbook_session.save; playbooks:write, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/playbook-sessions/{session_id}": { "get": { "tags": [ "Playbooks" ], "summary": "Read a playbook session", "description": "A session with its `ETag`, answers, notes, pinned version and completion receipts (scope `playbooks:read`).\nAnswers that write a custom field of the contact the source may not read are null (`redactedQuestionIds`).", "operationId": "getPlaybookSession", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The session with its answers, notes, pinned version and completion receipts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlaybookSession" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\"; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (playbooks:read) or FEATURE_DISABLED (api.tasks or crm.playbooks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PLAYBOOK_SESSION_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "patch": { "tags": [ "Playbooks" ], "summary": "Save the answers of a playbook session", "description": "Autosave answers and notes of an open session (scope `playbooks:write`, a delegated user) with optimistic\nconcurrency (`If-Match`): the same as the action `save`.", "operationId": "savePlaybookSession", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The session after the autosave, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlaybookSession" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\"; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (playbooks:write), FEATURE_DISABLED (api.tasks or crm.playbooks), DELEGATED_USER_REQUIRED (send X-AIO-Act-As or set a default user), DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PLAYBOOK_SESSION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "PLAYBOOK_SESSION_CLOSED (a completed or abandoned session is immutable), IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"\"; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, IF_MATCH_INVALID, PLAYBOOK_ANSWERS_INVALID (errors: questionId and code) or PLAYBOOK_NOTES_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Autosave of an open session: no CRM effect. Send If-Match with the ETag you read.", "properties": { "answers": { "type": [ "object", "null" ], "description": "Answers keyed by question ID of the pinned version; they replace the saved ones (null clears them). A null for a question in redactedQuestionIds keeps its saved answer." }, "notes": { "type": "string", "maxLength": 10000 } } }, "examples": { "answers": { "summary": "Save the answers so far", "value": { "answers": { "need": "Un equipo más grande", "budget": "High" }, "notes": "Pide una propuesta antes del viernes." } } } } } } } }, "/api/v1/playbooks": { "get": { "tags": [ "Playbooks" ], "summary": "List playbooks", "description": "Published sales playbooks (scope `playbooks:read`, features `api.tasks` and `crm.playbooks`), by cursor. Open a\nsession with `POST /api/v1/playbook-sessions` or the action `start_playbook` of a follow-up.", "operationId": "listPlaybooks", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Published playbooks of the company by name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlaybookPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (playbooks:read) or FEATURE_DISABLED (api.tasks or crm.playbooks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/playbooks/{playbook_id}": { "get": { "tags": [ "Playbooks" ], "summary": "Read a playbook", "description": "A published playbook with its current version: sections, questions, options, conditions and mapped custom fields\n(scope `playbooks:read`).", "operationId": "getPlaybook", "parameters": [ { "name": "playbook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Playbook Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The published playbook with its current version (definition).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiPlaybook" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\"; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (playbooks:read) or FEATURE_DISABLED (api.tasks or crm.playbooks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "PLAYBOOK_NOT_FOUND: missing, not published, archived or of another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/attribution": { "get": { "tags": [ "Reports" ], "summary": "Read the attribution report", "description": "Funnel and money per currency of each campaign (REPORT-01; scope `reports:read`, feature `marketing.tracking`).\nNo CSV.", "operationId": "getAttributionReport", "parameters": [ { "name": "campaignId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this campaign. At most 64 characters.", "title": "Campaignid" }, "description": "Only this campaign. At most 64 characters." }, { "name": "model", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "first or last touch. Default last.", "title": "Model" }, "description": "first or last touch. Default last." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start of the UTC period (date or date and time). At most 40 characters.", "title": "From" }, "description": "Start of the UTC period (date or date and time). At most 40 characters." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "End of the UTC period (exclusive). At most 40 characters.", "title": "To" }, "description": "End of the UTC period (exclusive). At most 40 characters." }, { "name": "currency", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 4217 code. At most 3 characters.", "title": "Currency" }, "description": "ISO 4217 code. At most 3 characters." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The attribution report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportAttribution" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or marketing.tracking).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/campaigns/{campaign_id}": { "get": { "tags": [ "Reports" ], "summary": "Read the results of a campaign", "description": "Aggregated metrics, links and the A/B report of a campaign (`marketing_engagement.analytics`; scope\n`reports:read`; a push campaign also needs `marketing.push`).", "operationId": "getCampaignReport", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Campaign Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The results of the campaign.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportCampaign" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or marketing.push for a push campaign).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CAMPAIGN_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/csat/funnel": { "get": { "tags": [ "Reports" ], "summary": "Read the CSAT funnel", "description": "The survey funnel (CSAT-04; scope `reports:read`, feature `support.csat_auto`). No CSV.", "operationId": "getCsatFunnelReport", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Closes of the last N days. Whole number 1-366. Default 30.", "title": "Days" }, "description": "Closes of the last N days. Whole number 1-366. Default 30." }, { "name": "basis", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "closed, accepted or responded (CSAT cohort). One of: closed, accepted, responded. Default responded.", "title": "Basis" }, "description": "closed, accepted or responded (CSAT cohort). One of: closed, accepted, responded. Default responded." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Grouping of the funnel. One of: none, channel, inbox, agent, team, label. Default none.", "title": "Groupby" }, "description": "Grouping of the funnel. One of: none, channel, inbox, agent, team, label. Default none." }, { "name": "channel", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Channel" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "mailbox", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Mailbox" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "agentId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Agentid" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "teamId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Teamid" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "labelId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Labelid" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "category", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Category" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Pipelineid" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Source" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Status" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "reason", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Reason" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "cycle", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID).", "title": "Cycle" }, "description": "Funnel filter (validated as in the app: 422 CSAT_FUNNEL_FILTER_INVALID)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The CSAT funnel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportCsatFunnel" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or support.csat_auto).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/dashboard": { "get": { "tags": [ "Reports" ], "summary": "Read the dashboard", "description": "The dashboard of the app (`main.dashboard`): inbox counters, volume of the week and latest conversations (scope\n`reports:read`; previews and subjects only with `support:content`).", "operationId": "getDashboardReport", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The dashboard of the app.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportDashboard" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/sales": { "get": { "tags": [ "Reports" ], "summary": "Read the sales report", "description": "Recorded deal history and the current snapshot (`crm_business.sales_reports`; scope `reports:read`). No CSV.", "operationId": "getSalesReport", "parameters": [ { "name": "dateFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First UTC day of the recorded history. YYYY-MM-DD.", "title": "Datefrom" }, "description": "First UTC day of the recorded history. YYYY-MM-DD." }, { "name": "dateTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last UTC day of the recorded history. YYYY-MM-DD.", "title": "Dateto" }, "description": "Last UTC day of the recorded history. YYYY-MM-DD." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the deals of this user. At most 64 characters.", "title": "Ownerid" }, "description": "Only the deals of this user. At most 64 characters." }, { "name": "stage", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only the history entries of this stage. One of: (empty), lead, qualified, proposal, negotiation, won, lost.", "title": "Stage" }, "description": "Only the history entries of this stage. One of: (empty), lead, qualified, proposal, negotiation, won, lost." }, { "name": "currency", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 4217 code (three capital letters).", "title": "Currency" }, "description": "ISO 4217 code (three capital letters)." }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact source of the deals. At most 120 characters.", "title": "Source" }, "description": "Exact source of the deals. At most 120 characters." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Grouping of the history. One of: owner, stage, date, source. Default owner.", "title": "Groupby" }, "description": "Grouping of the history. One of: owner, stage, date, source. Default owner." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The sales report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSales" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/sales/forecast": { "get": { "tags": [ "Reports" ], "summary": "Read the sales forecast", "description": "The forecast of one period (PIPE-06; scope `reports:read`, feature `crm.pipeline_insights`).", "operationId": "getSalesForecastReport", "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "month (default), quarter or year. At most 16 characters.", "title": "Period" }, "description": "month (default), quarter or year. At most 16 characters." }, { "name": "periodDate", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A day of the period (YYYY-MM-DD, company zone). At most 10 characters.", "title": "Perioddate" }, "description": "A day of the period (YYYY-MM-DD, company zone). At most 10 characters." }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A sales pipeline (every one by default). At most 64 characters.", "title": "Pipelineid" }, "description": "A sales pipeline (every one by default). At most 64 characters." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A user or unassigned. At most 64 characters.", "title": "Ownerid" }, "description": "A user or unassigned. At most 64 characters." }, { "name": "currency", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 4217 code. At most 3 characters.", "title": "Currency" }, "description": "ISO 4217 code. At most 3 characters." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "none, owner or pipeline. At most 16 characters.", "title": "Groupby" }, "description": "none, owner or pipeline. At most 16 characters." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The sales forecast of the period.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSalesForecast" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or crm.pipeline_insights).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/sales/goals": { "get": { "tags": [ "Reports" ], "summary": "Read the sales goals", "description": "Goals with the progress of the period (PIPE-07; scope `reports:read`, feature `crm.pipeline_insights`).", "operationId": "getSalesGoalsReport", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "active (default) or archived. At most 12 characters.", "title": "Status" }, "description": "active (default) or archived. At most 12 characters." }, { "name": "scope", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "company or user. At most 12 characters.", "title": "Scope" }, "description": "company or user. At most 12 characters." }, { "name": "userId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Goals of this user. At most 64 characters.", "title": "Userid" }, "description": "Goals of this user. At most 64 characters." }, { "name": "metric", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "won_value, won_deals, created_deals or completed_activities. At most 24 characters.", "title": "Metric" }, "description": "won_value, won_deals, created_deals or completed_activities. At most 24 characters." }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Goals of this pipeline. At most 64 characters.", "title": "Pipelineid" }, "description": "Goals of this pipeline. At most 64 characters." }, { "name": "periodKind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "month, quarter or year. At most 12 characters.", "title": "Periodkind" }, "description": "month, quarter or year. At most 12 characters." }, { "name": "periodDate", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The period whose progress is shown (YYYY-MM-DD). At most 10 characters.", "title": "Perioddate" }, "description": "The period whose progress is shown (YYYY-MM-DD). At most 10 characters." }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Goals to skip. Whole number 0-1000000. Default 0.", "title": "Offset" }, "description": "Goals to skip. Whole number 0-1000000. Default 0." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Goals per page. Whole number 1-100. Default 50.", "title": "Limit" }, "description": "Goals per page. Whole number 1-100. Default 50." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The sales goals and their progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSalesGoals" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or crm.pipeline_insights).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/sales/insights/{report}": { "get": { "tags": [ "Reports" ], "summary": "Read a sales insight", "description": "Conversion, duration, progress or results (PIPE-05; scope `reports:read`, feature `crm.pipeline_insights`).", "operationId": "getSalesInsightReport", "parameters": [ { "name": "report", "in": "path", "required": true, "schema": { "type": "string", "description": "conversion, duration, progress or results.", "title": "Report" }, "description": "conversion, duration, progress or results." }, { "name": "period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "month (default), quarter, year, week, day or custom. At most 16 characters.", "title": "Period" }, "description": "month (default), quarter, year, week, day or custom. At most 16 characters." }, { "name": "periodDate", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A day of the period (YYYY-MM-DD, company zone); today by default. At most 10 characters.", "title": "Perioddate" }, "description": "A day of the period (YYYY-MM-DD, company zone); today by default. At most 10 characters." }, { "name": "dateFrom", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First local day of a custom period. At most 10 characters.", "title": "Datefrom" }, "description": "First local day of a custom period. At most 10 characters." }, { "name": "dateTo", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last local day of a custom period. At most 10 characters.", "title": "Dateto" }, "description": "Last local day of a custom period. At most 10 characters." }, { "name": "asOf", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Observation cut-off (exclusive; now by default, never later). At most 40 characters.", "title": "Asof" }, "description": "Observation cut-off (exclusive; now by default, never later). At most 40 characters." }, { "name": "cohort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "created (default) or pipeline_entry. At most 20 characters.", "title": "Cohort" }, "description": "created (default) or pipeline_entry. At most 20 characters." }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A sales pipeline (the default one when absent, except results). At most 64 characters.", "title": "Pipelineid" }, "description": "A sales pipeline (the default one when absent, except results). At most 64 characters." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A user or unassigned. At most 64 characters.", "title": "Ownerid" }, "description": "A user or unassigned. At most 64 characters." }, { "name": "ownerBasis", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "creation, entry, current or close. At most 16 characters.", "title": "Ownerbasis" }, "description": "creation, entry, current or close. At most 16 characters." }, { "name": "currency", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 4217 code. At most 3 characters.", "title": "Currency" }, "description": "ISO 4217 code. At most 3 characters." }, { "name": "source", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Exact source of the deals. At most 120 characters.", "title": "Source" }, "description": "Exact source of the deals. At most 120 characters." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "none, owner, pipeline or period (results). At most 16 characters.", "title": "Groupby" }, "description": "none, owner, pipeline or period (results). At most 16 characters." }, { "name": "interval", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "day, week, month or quarter (groupBy=period). At most 16 characters.", "title": "Interval" }, "description": "day, week, month or quarter (groupBy=period). At most 16 characters." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "One sales insight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSalesInsight" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or crm.pipeline_insights).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/sequences": { "get": { "tags": [ "Reports" ], "summary": "Read the results of the sales sequences", "description": "Cohorts or events of the sales sequences (SEQ-07; scope `reports:read`, feature `crm.sequences`).", "operationId": "getSequenceReport", "parameters": [ { "name": "mode", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "cohort (enrollments started in the range) or events. One of: cohort, events. Default cohort.", "title": "Mode" }, "description": "cohort (enrollments started in the range) or events. One of: cohort, events. Default cohort." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "version, owner or period. One of: version, owner, period. Default version.", "title": "Groupby" }, "description": "version, owner or period. One of: version, owner, period. Default version." }, { "name": "period", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "week or month (groupBy=period). One of: week, month. Default month.", "title": "Period" }, "description": "week or month (groupBy=period). One of: week, month. Default month." }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First local day; 90 days ago by default. YYYY-MM-DD.", "title": "From" }, "description": "First local day; 90 days ago by default. YYYY-MM-DD." }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last local day; today by default. YYYY-MM-DD.", "title": "To" }, "description": "Last local day; today by default. YYYY-MM-DD." }, { "name": "sequenceId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this sequence. At most 64 characters.", "title": "Sequenceid" }, "description": "Only this sequence. At most 64 characters." }, { "name": "ownerUserId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this salesperson. At most 64 characters.", "title": "Owneruserid" }, "description": "Only this salesperson. At most 64 characters." }, { "name": "versionId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only this version. At most 64 characters.", "title": "Versionid" }, "description": "Only this version. At most 64 characters." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Results of the sales sequences.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSequences" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks or crm.sequences).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/support": { "get": { "tags": [ "Reports" ], "summary": "Read the support report", "description": "Support conversations of the last N days (`support_reports.support_report`; scope `reports:read`; the customers'\ncomments only with `support:content`). No CSV.", "operationId": "getSupportReport", "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Conversations created in the last N days. Whole number 1-366. Default 30.", "title": "Days" }, "description": "Conversations created in the last N days. Whole number 1-366. Default 30." }, { "name": "groupBy", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "channel, agent, inbox, team or label. One of: channel, agent, inbox, team, label. Default channel.", "title": "Groupby" }, "description": "channel, agent, inbox, team or label. One of: channel, agent, inbox, team, label. Default channel." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The support report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSupport" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/reports/support/live": { "get": { "tags": [ "Reports" ], "summary": "Read the live support counters", "description": "Open, pending and unassigned conversations now (`support_reports.support_report_live`; scope `reports:read`).", "operationId": "getSupportLiveReport", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The live support counters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiReportSupportLive" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (reports:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED, VALIDATION_ERROR (field, reason) or the report's own code (REPORT_TOO_LARGE, RANGE_TOO_LONG…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/sales-mailboxes": { "get": { "tags": [ "Sequences" ], "summary": "List sales mailboxes", "description": "The salespeople's mailboxes: owner, provider, state and health, never the address or tokens (scope\n`sequences:read`). Reconnecting is OAuth in the app.", "operationId": "listSalesMailboxes", "parameters": [ { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Of this salesperson (the mailbox owner).", "title": "Ownerid" }, "description": "Of this salesperson (the mailbox owner)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "pending, ready, paused or revoked.", "examples": [ "revoked" ], "title": "Status" }, "description": "pending, ready, paused or revoked." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Sales mailboxes of the company: owner and state, never the address or tokens.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSalesMailboxPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sequences:read) or FEATURE_DISABLED (api.tasks or crm.sequences).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/segments": { "get": { "tags": [ "Segments" ], "summary": "List segments", "description": "The saved segments of the company with their filters (scope `segments:read`); the values of personal filters\n(`q`, `company`, rules on name, email, phone, company or custom fields) are null unless the key reads those fields\nof every contact (`hiddenFilters`).", "operationId": "listSegments", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Saved segments of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSegmentPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (segments:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/segments/preview": { "post": { "tags": [ "Segments" ], "summary": "Preview a segment", "description": "Counts, coverage and fingerprint of a saved segment or of filters, never the contacts (scope `segments:read`;\nbehavior conditions need `marketing.behavior`). Only filters without personal data: `q` is never accepted and\n`company` or rules on name, email, phone, company or custom fields need `contacts:read`, `contactScope` company and\nthose fields among the source's read fields (422 `FIELD_NOT_ALLOWED`, reason `personal_field`).", "operationId": "previewSegment", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Counts, coverage and fingerprint of the audience; never contacts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSegmentPreview" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (segments:read), FEATURE_DISABLED (api.tasks; marketing.behavior for behavior conditions) or LEGAL_BASIS_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "SEGMENT_NOT_FOUND: the segment does not exist or belongs to another company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED (an unknown field, or reason personal_field: filters.q always, filters.company or filters.rules on name, email, phone, company or custom fields unless the key reads them of every contact), VALIDATION_ERROR (field), BEHAVIOR_* or SEGMENT_PREVIEW_TIMEOUT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "A saved segment (segmentId) or filters without personal data (language, tag, rules on language, tags, createdAt or score, behavior); neither previews every contact. The preview only counts: q is never accepted and company or rules on name, email, phone, company or custom fields need contacts:read, contactScope company and those fields among the source's read fields (422 FIELD_NOT_ALLOWED, reason personal_field, otherwise).", "properties": { "filters": { "type": "object", "description": "ContactFilters without personal data.", "properties": { "language": { "type": "string", "enum": [ "", "es", "en" ] }, "tag": { "type": "string", "maxLength": 40 }, "rules": { "type": [ "object", "null" ], "description": "AND/OR tree of conditions (op/conditions; field, operator, value, valueTo) on language, tags, createdAt or score." }, "behavior": { "type": [ "object", "null" ], "description": "Behavior conditions (marketing.behavior)." }, "q": { "type": "string", "description": "Not accepted: 422 FIELD_NOT_ALLOWED (search with POST /api/v1/contacts/search)." }, "company": { "type": "string", "description": "Only for a key that reads the company of every contact." }, "companyMatch": { "type": "string", "enum": [ "exact", "contains" ] } } }, "segmentId": { "type": "string" } } }, "examples": { "segment": { "summary": "Count a saved segment", "value": { "segmentId": "5e9a" } }, "filters": { "summary": "Count the Spanish contacts with a tag", "value": { "filters": { "language": "es", "tag": "vip" } } } } } } } } }, "/api/v1/sequence-enrollments": { "get": { "tags": [ "Sequences" ], "summary": "List sales sequence enrollments", "description": "Enrollments newest first with a cursor (scope `sequences:read`); only IDs go in the URL.", "operationId": "listSequenceEnrollments", "parameters": [ { "name": "sequenceId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Enrollments of this sequence.", "title": "Sequenceid" }, "description": "Enrollments of this sequence." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "live, ended or one status (active, waiting_time, waiting_task, paused, delivery_uncertain, stopped_*, cancelled, completed).", "examples": [ "paused" ], "title": "Status" }, "description": "live, ended or one status (active, waiting_time, waiting_task, paused, delivery_uncertain, stopped_*, cancelled, completed)." }, { "name": "ownerId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Of this salesperson (the mailbox owner).", "title": "Ownerid" }, "description": "Of this salesperson (the mailbox owner)." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Enrollments of this contact (an absorbed contact's count for its kept record).", "title": "Contactid" }, "description": "Enrollments of this contact (an absorbed contact's count for its kept record)." }, { "name": "dealId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Enrollments of this deal.", "title": "Dealid" }, "description": "Enrollments of this deal." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Enrollments of the company, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSequenceEnrollmentPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sequences:read) or FEATURE_DISABLED (api.tasks or crm.sequences).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/sequence-enrollments/{enrollment_id}": { "get": { "tags": [ "Sequences" ], "summary": "Read a sales sequence enrollment", "description": "An enrollment with its `ETag`, steps, executions, decisions and what resuming would need (scope `sequences:read`).", "operationId": "getSequenceEnrollment", "parameters": [ { "name": "enrollment_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Enrollment Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The enrollment with its steps, executions, decisions and what resuming needs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSequenceEnrollment" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\"; send it back as If-Match of the actions.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sequences:read) or FEATURE_DISABLED (api.tasks or crm.sequences).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "ENROLLMENT_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/sequence-enrollments/{resource_id}/actions/{action}": { "post": { "tags": [ "Sequences" ], "summary": "Run an action of a sales sequence enrollment", "description": "Run an action of a sequence-enrollments resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runSequenceEnrollmentAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "cancel": { "summary": "Cancel the enrollment (sales_enrollment.cancel; sequences:execute, delegated)", "value": { "input": { "reason": "The customer already bought" } } }, "pause": { "summary": "Pause the enrollment (sales_enrollment.pause; sequences:execute, delegated)", "value": { "input": { "reason": "The customer is on holiday" } } }, "reconcile_execution": { "summary": "Reconcile with the mailbox (sales_enrollment.reconcile_execution; sequences:execute, delegated)", "value": { "input": {} } }, "resume": { "summary": "Resume the enrollment (sales_enrollment.resume; sequences:execute, owner)", "value": { "input": {} } }, "review_execution": { "summary": "Review the send (sales_enrollment.review_execution; sequences:execute, delegated)", "value": { "input": { "decision": "confirm_accepted", "evidence": "Seen in the sent folder of the mailbox at 09:02" } } }, "skip_step": { "summary": "Skip the step (sales_enrollment.skip_step; sequences:execute, owner)", "value": { "input": { "reason": "Confirmed with the customer by phone" } } } } } } } } }, "/api/v1/sequences": { "get": { "tags": [ "Sequences" ], "summary": "List sales sequences", "description": "Sales sequences by cursor (scope `sequences:read`, features `api.tasks` and `crm.sequences`). Enroll contacts with\n`POST /api/v1/sequences/{id}/enrollments`.", "operationId": "listSalesSequences", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "active (default: not archived), all, draft, published, paused or archived.", "examples": [ "published" ], "title": "Status" }, "description": "active (default: not archived), all, draft, published, paused or archived." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Sales sequences of the company, newest change first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSalesSequencePage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sequences:read) or FEATURE_DISABLED (api.tasks or crm.sequences).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/sequences/{resource_id}/actions/{action}": { "post": { "tags": [ "Sequences" ], "summary": "Run an action of a sales sequence", "description": "Run an action of a sequences resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runSalesSequenceAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "pause": { "summary": "Pause the sequence (sales_sequence.pause; sequences:execute, delegated)", "value": { "input": {} } }, "resume": { "summary": "Resume the sequence (sales_sequence.resume; sequences:execute, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/sequences/{sequence_id}": { "get": { "tags": [ "Sequences" ], "summary": "Read a sales sequence", "description": "A sequence with its published version: the structure of its steps, never the email bodies (scope\n`sequences:read`).", "operationId": "getSalesSequence", "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sequence Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The sequence with its published version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSalesSequence" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\"; send it back as If-Match of the actions.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sequences:read) or FEATURE_DISABLED (api.tasks or crm.sequences).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "SEQUENCE_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/sequences/{sequence_id}/enrollments": { "post": { "tags": [ "Sequences" ], "summary": "Enroll contacts in a sales sequence", "description": "Up to 100 contacts with the delegated salesperson's own ready mailbox (scope `sequences:execute`, the owner as\n`X-AIO-Act-As`): `dryRun` returns the eligible contacts and the exclusions without reserving anything; the execution\nneeds an `Idempotency-Key` (the same key never enrolls twice).", "operationId": "enrollInSalesSequence", "parameters": [ { "name": "sequence_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Sequence Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "dryRun: the enroll-preview and its previewFingerprint; execution: one result per contact, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSequenceEnrollAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sequences:execute), FEATURE_DISABLED (api.tasks or crm.sequences), DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE or MAILBOX_OWNER_REQUIRED (the delegated user has no ready sales mailbox).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "SEQUENCE_NOT_FOUND, VERSION_NOT_FOUND or OPPORTUNITY_NOT_FOUND (another company's records answer the same).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "SEQUENCE_NOT_ENROLLABLE, MAILBOX_NOT_READY, MAILBOX_CHECK_STALE, SIGNATURE_REQUIRED, MEETING_CALENDAR_REQUIRED, OPPORTUNITY_REQUIRED, OPPORTUNITY_CLOSED, PREVIEW_STALE (fingerprint), MERGED_RECORD (canonicalId), IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (more than 100 contacts), START_IN_PAST or START_TOO_FAR.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "input" ], "properties": { "input": { "type": "object", "additionalProperties": false, "required": [ "contactIds" ], "properties": { "contactIds": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string", "maxLength": 64 }, "description": "Up to 100 contacts." }, "versionId": { "type": [ "string", "null" ], "description": "Default: the latest published version." }, "dealId": { "type": [ "string", "null" ], "description": "Enroll the contact of this deal." }, "startAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Within 90 days; default now." }, "reason": { "type": [ "string", "null" ], "maxLength": 500, "description": "Required for a contact that was enrolled before." }, "previewFingerprint": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{64}$", "description": "Optional: the confirm.previewFingerprint of the dryRun; a change since then is 409 PREVIEW_STALE." } } }, "dryRun": { "type": "boolean", "default": false, "description": "true: only the enroll-preview (eligible contacts and exclusions); nothing is reserved and no Idempotency-Key is needed." } } }, "examples": { "preview": { "summary": "1) Preview: eligible contacts and the reason of each exclusion", "value": { "dryRun": true, "input": { "contactIds": [ "77aa0000-0000-4000-8000-000000000001", "77aa0000-0000-4000-8000-000000000002" ] } } }, "enroll": { "summary": "2) Enroll (Idempotency-Key required) with the delegated owner's mailbox", "value": { "input": { "contactIds": [ "77aa0000-0000-4000-8000-000000000001" ], "previewFingerprint": "3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f3f" } } } } } } } } }, "/api/v1/sites": { "get": { "tags": [ "Sites" ], "summary": "List websites", "description": "The websites of the company with their verification task, never the verification code (scope `sites:read`).", "operationId": "listSites", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Websites of the company (archived last).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSitePage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sites:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/sites/{resource_id}/actions/{action}": { "post": { "tags": [ "Sites" ], "summary": "Run an action of a website", "description": "Run an action of a sites resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runSiteAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "pause": { "summary": "Pause (marketing_site.pause; sites:admin, delegated)", "value": { "input": {} } }, "resume": { "summary": "Resume (marketing_site.resume; sites:admin, delegated)", "value": { "input": {} } }, "verify": { "summary": "Verify (marketing_site.verify; sites:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/sites/{site_id}": { "get": { "tags": [ "Sites" ], "summary": "Read a website", "description": "A website with its verification state, task, actions and `ETag`; never the verification code (scope\n`sites:read`).", "operationId": "getSite", "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Site Id" } }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The website with its verification state, task, actions and ETag; never the verification code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSite" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the website; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (sites:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "SITE_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/subscriptions/invite": { "post": { "tags": [ "Contacts" ], "summary": "Invite to subscribe (double opt-in)", "description": "Queue the double opt-in email with the source's SMTP connection (scope `subscriptions:invite`). Only the\nperson's confirmation grants the permission.", "operationId": "inviteSubscription", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "202": { "description": "Accepted: the double opt-in email is queued unless the address is suppressed or already pending (the answer is the same). No permission is granted until the person confirms.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "enum": [ "pending" ] }, "message": { "type": "string" } }, "description": "The same answer whether an email is queued, already pending or suppressed." } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "429": { "description": "Quota reached before anything was written: RATE_LIMITED (quota key, company or companyEventsPerDay) or API_AUTH_THROTTLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "403": { "description": "API_SCOPE_REQUIRED (subscriptions:invite) or FEATURE_DISABLED.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "404": { "description": "CONTACT_NOT_FOUND: the contactId or externalId is not a contact the source reaches.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "409": { "description": "INVITE_CONNECTION_REQUIRED, INVITE_CONNECTION_NOT_READY, SUBJECT_IDENTITY_CONFLICT or MARKETING_SEND_DISABLED (marketing sending is off on the server: nothing is queued).", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "413": { "description": "Body above 32 KiB.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } }, "422": { "description": "CONTACT_BODY_INVALID, CONTACT_FIELD_UNKNOWN, INVITE_FIELD_INVALID, INVITE_SUBJECT_REQUIRED, INVITE_EMAIL_INVALID, INVITE_EMAIL_MISMATCH, CONTACT_EMAIL_MISSING, EXTERNAL_ID_INVALID…", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "object", "required": [ "code", "message" ], "additionalProperties": true, "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } } } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "policyVersion", "policyText", "evidence" ], "properties": { "contactId": { "type": "string", "description": "A contact the source reaches (it must have an email)." }, "externalId": { "type": "string", "description": "Your customer ID for this source: 1-128 visible ASCII characters, never an email or a phone.", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$", "examples": [ "customer_872" ] }, "email": { "type": "string", "description": "Address to invite; with a contact it must be the contact's email.", "maxLength": 254, "format": "email" }, "name": { "type": "string", "description": "Name for the confirmation email when no contact is given.", "maxLength": 160 }, "purpose": { "type": "string", "description": "Purpose of the permission that the confirmation would grant.", "pattern": "^[a-z][a-z0-9_-]{0,63}$", "default": "marketing" }, "policyVersion": { "type": "string", "description": "Version of the notice the person accepts.", "minLength": 1, "maxLength": 160 }, "policyText": { "type": "string", "description": "Text of the notice shown in the confirmation email.", "minLength": 1, "maxLength": 2000 }, "evidence": { "type": "string", "description": "How the person asked to be invited (kept as evidence of the request).", "minLength": 1, "maxLength": 2000 } }, "description": "At least one of contactId, externalId or email. It never grants a permission." }, "examples": { "linkedCustomer": { "summary": "Invite a linked customer to the newsletter", "value": { "externalId": "customer_872", "purpose": "marketing", "policyVersion": "newsletter-2026-09", "policyText": "Quiero recibir novedades por email. Puedo darme de baja en cualquier momento.", "evidence": "Checkbox unchecked by default ticked at checkout, order 842" } } } } } } } }, "/api/v1/support-teams": { "get": { "tags": [ "Support" ], "summary": "List the support teams", "description": "The support teams with their channels and members (scope `support:read`).", "operationId": "listSupportTeams", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Support teams of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSupportTeams" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/support/overview": { "get": { "tags": [ "Support" ], "summary": "Read the support overview", "description": "Assignment policy, opening hours, teams and agents with availability and load (scope `support:read`).", "operationId": "getSupportOverview", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Support policy, opening hours, teams and agents with their load.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiSupportOverview" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/task-changes": { "get": { "tags": [ "Tasks" ], "summary": "Read the change feed", "description": "The last state of every task changed after the cursor, in order and at least once; tasks this key cannot read\nare left out but the cursor advances. `410 CURSOR_EXPIRED` means: synchronize again.", "operationId": "listTaskChanges", "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The cursor of GET /api/v1/task-changes/cursor or nextCursor of the previous page.", "title": "Cursor" }, "description": "The cursor of GET /api/v1/task-changes/cursor or nextCursor of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-500 (100 by default).", "examples": [ "100" ], "title": "Limit" }, "description": "1-500 (100 by default)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Changes after the cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskChanges" }, "examples": { "page": { "summary": "Changes since your cursor", "value": { "items": [ { "taskId": "support.ticket:9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "kind": "support.ticket", "change": "upsert", "status": "done", "version": 19, "changedAt": "2026-09-29T10:20:02Z" }, { "taskId": "crm.duplicate_review:contact:0b1c2d3e:7f8a9b0c", "kind": "crm.duplicate_review", "change": "deleted", "status": "cancelled", "version": 3, "changedAt": "2026-09-29T10:20:05Z" } ], "nextCursor": "c1.…", "hasMore": false, "indexedThrough": "2026-09-29T10:20:07Z" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks). Kinds whose area the key cannot read are simply left out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered or made for another company or source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "410": { "description": "CURSOR_EXPIRED: the feed purged that stretch (30 days); synchronize again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "VALIDATION_ERROR (cursor required, limit 1-500).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/task-changes/cursor": { "get": { "tags": [ "Tasks" ], "summary": "Read the current cursor of the change feed", "description": "The current position of the change feed. Read it **before** the initial load with `GET /api/v1/tasks`.", "operationId": "getTaskChangesCursor", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The current cursor of the change feed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskChangesCursor" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks). Kinds whose area the key cannot read are simply left out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/task-kinds": { "get": { "tags": [ "Tasks" ], "summary": "List the task kinds", "description": "The catalog of task kinds this key can read: statuses, signals, PATCH fields, completion action and actions with\nscope, actor, preview and the JSON schema of their input (feature `api.tasks`).", "operationId": "listTaskKinds", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The kinds this key can read (area scope and features on) with statuses, signals, PATCH fields, completion and actions with the JSON schema of their input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskKinds" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/task-summary": { "get": { "tags": [ "Tasks" ], "summary": "Count tasks", "description": "Counts per kind, status and assignee with the same filters as the list, for dashboards.", "operationId": "getTaskSummary", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated kinds (up to 10), for example support.ticket,crm.activity.", "title": "Kind" }, "description": "Comma-separated kinds (up to 10), for example support.ticket,crm.activity." }, { "name": "area", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated areas (up to 10).", "title": "Area" }, "description": "Comma-separated areas (up to 10)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated statuses; open,in_progress,waiting,needs_review by default.", "title": "Status" }, "description": "Comma-separated statuses; open,in_progress,waiting,needs_review by default." }, { "name": "assigneeId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tasks of this user (or routing contact).", "title": "Assigneeid" }, "description": "Tasks of this user (or routing contact)." }, { "name": "assignee", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "me: tasks of the delegated user (X-AIO-Act-As or the default user).", "examples": [ "me" ], "title": "Assignee" }, "description": "me: tasks of the delegated user (X-AIO-Act-As or the default user)." }, { "name": "unassigned", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: tasks without assignee.", "examples": [ "true" ], "title": "Unassigned" }, "description": "true: tasks without assignee." }, { "name": "teamId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tasks of this team.", "title": "Teamid" }, "description": "Tasks of this team." }, { "name": "dueBefore", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly before.", "title": "Duebefore" }, "description": "RFC 3339: due strictly before." }, { "name": "dueAfter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly after.", "title": "Dueafter" }, "description": "RFC 3339: due strictly after." }, { "name": "overdue", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: tasks with the overdue signal.", "examples": [ "true" ], "title": "Overdue" }, "description": "true: tasks with the overdue signal." }, { "name": "signal", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated signals (any of them).", "title": "Signal" }, "description": "Comma-separated signals (any of them)." }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated priorities: low, normal, high, urgent.", "title": "Priority" }, "description": "Comma-separated priorities: low, normal, high, urgent." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked contact ID (never personal data in the URL).", "title": "Contactid" }, "description": "Linked contact ID (never personal data in the URL)." }, { "name": "dealId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked deal ID.", "title": "Dealid" }, "description": "Linked deal ID." }, { "name": "ticketId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked ticket ID.", "title": "Ticketid" }, "description": "Linked ticket ID." }, { "name": "conversationId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked conversation ID.", "title": "Conversationid" }, "description": "Linked conversation ID." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: tasks whose observed change (updatedAt) is at or after it.", "title": "Updatedsince" }, "description": "RFC 3339: tasks whose observed change (updatedAt) is at or after it." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "Counts per kind, status and assignee with the filters of the list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskSummary" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks). Kinds whose area the key cannot read are simply left out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "VALIDATION_ERROR (field: a filter, sort or limit) or DELEGATED_USER_REQUIRED (assignee=me without a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/tasks": { "get": { "tags": [ "Tasks" ], "summary": "List tasks", "description": "The tasks of every kind the key can read, filtered on the task index and hydrated live with their `ETag` and\nactions (feature `api.tasks`; each kind needs `:read` and its features).", "operationId": "listTasks", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated kinds (up to 10), for example support.ticket,crm.activity.", "title": "Kind" }, "description": "Comma-separated kinds (up to 10), for example support.ticket,crm.activity." }, { "name": "area", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated areas (up to 10).", "title": "Area" }, "description": "Comma-separated areas (up to 10)." }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated statuses; open,in_progress,waiting,needs_review by default.", "title": "Status" }, "description": "Comma-separated statuses; open,in_progress,waiting,needs_review by default." }, { "name": "assigneeId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tasks of this user (or routing contact).", "title": "Assigneeid" }, "description": "Tasks of this user (or routing contact)." }, { "name": "assignee", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "me: tasks of the delegated user (X-AIO-Act-As or the default user).", "examples": [ "me" ], "title": "Assignee" }, "description": "me: tasks of the delegated user (X-AIO-Act-As or the default user)." }, { "name": "unassigned", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: tasks without assignee.", "examples": [ "true" ], "title": "Unassigned" }, "description": "true: tasks without assignee." }, { "name": "teamId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tasks of this team.", "title": "Teamid" }, "description": "Tasks of this team." }, { "name": "dueBefore", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly before.", "title": "Duebefore" }, "description": "RFC 3339: due strictly before." }, { "name": "dueAfter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: due strictly after.", "title": "Dueafter" }, "description": "RFC 3339: due strictly after." }, { "name": "overdue", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "true: tasks with the overdue signal.", "examples": [ "true" ], "title": "Overdue" }, "description": "true: tasks with the overdue signal." }, { "name": "signal", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated signals (any of them).", "title": "Signal" }, "description": "Comma-separated signals (any of them)." }, { "name": "priority", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated priorities: low, normal, high, urgent.", "title": "Priority" }, "description": "Comma-separated priorities: low, normal, high, urgent." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked contact ID (never personal data in the URL).", "title": "Contactid" }, "description": "Linked contact ID (never personal data in the URL)." }, { "name": "dealId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked deal ID.", "title": "Dealid" }, "description": "Linked deal ID." }, { "name": "ticketId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked ticket ID.", "title": "Ticketid" }, "description": "Linked ticket ID." }, { "name": "conversationId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Linked conversation ID.", "title": "Conversationid" }, "description": "Linked conversation ID." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: tasks whose observed change (updatedAt) is at or after it.", "title": "Updatedsince" }, "description": "RFC 3339: tasks whose observed change (updatedAt) is at or after it." }, { "name": "sort", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "dueAt (default, without date last), -updatedAt, -priority or createdAt.", "examples": [ "dueAt" ], "title": "Sort" }, "description": "dueAt (default, without date last), -updatedAt, -priority or createdAt." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page.", "title": "Cursor" }, "description": "nextCursor of the previous page." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "A page of tasks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskList" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "FEATURE_DISABLED (api.tasks). Kinds whose area the key cannot read are simply left out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired (24 h) or made for another company, source or query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "VALIDATION_ERROR (field: a filter, sort or limit) or DELEGATED_USER_REQUIRED (assignee=me without a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Tasks" ], "summary": "Create a task", "description": "Create a task of a creatable kind (`crm.activity`) through the same function as the UI; `Idempotency-Key` is\nrequired and `externalLink` optional.", "operationId": "createTask", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "201": { "description": "Created through the same internal function as the UI.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTask" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new task.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (the create scope of the kind, activities:write), FEATURE_DISABLED or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same key, another body), IDEMPOTENCY_IN_PROGRESS, EXTERNAL_ID_TAKEN, MERGED_RECORD…", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "TASK_KIND_NOT_CREATABLE (creatable), FIELD_NOT_ALLOWED, VALIDATION_ERROR, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE, EXTERNAL_LINK_URL_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "kind" ], "additionalProperties": true, "description": "kind plus the fields of its creation schema (GET /api/v1/task-kinds, create.inputSchema).", "properties": { "kind": { "type": "string", "description": "A kind with creatable=true (crm.activity)." }, "externalLink": { "type": "object", "additionalProperties": false, "required": [ "externalId", "url" ], "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your ID: visible ASCII, never an email or a phone; one task per externalId and source." }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS, without credentials." } } } } }, "examples": { "activity": { "summary": "A follow-up linked to a ticket", "value": { "kind": "crm.activity", "title": "Llamar para renovar", "activityKind": "call", "dueAt": "2026-10-02T09:00:00Z", "priority": "high", "externalLink": { "externalId": "PROJ-88", "url": "https://tool.example.com/browse/PROJ-88" } } } } } } } } }, "/api/v1/tasks/lookup": { "post": { "tags": [ "Tasks" ], "summary": "Find a task by your externalId", "description": "The task linked by **this** source to your `externalId` (the ID goes in the body, never in the URL).", "operationId": "lookupTask", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "The task linked by this source to the externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTask" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:read of the kind) or FEATURE_DISABLED (api.tasks or the kind's feature).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: no task of this source has that externalId.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE or EXTERNAL_ID_PHONE_SHAPE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "externalId" ], "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128 } } }, "examples": { "jira": { "summary": "The task your tool linked as SUP-431", "value": { "externalId": "SUP-431" } } } } } } } }, "/api/v1/tasks/{task_id}": { "get": { "tags": [ "Tasks" ], "summary": "Read a task", "description": "The live task with its `ETag` and the availability of its actions for this key and delegated user (scope\n`:read` of the kind).", "operationId": "getTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "The live task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTask" }, "examples": { "ticket": { "summary": "A ticket waiting for the customer", "value": { "id": "support.ticket:9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "kind": "support.ticket", "area": "support", "schemaVersion": 1, "title": "No llega la factura de septiembre", "status": "waiting", "sourceStatus": "waiting_customer", "signals": [ "sla_resolution_at_risk" ], "priority": "high", "assignee": { "type": "user", "id": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "name": "Ana Ruiz" }, "team": { "id": "a81e0c6b2d4f4a1e8b9c7d5e3f1a2b3c", "name": "Facturación" }, "dueAt": "2026-09-30T16:00:00Z", "dueKind": "sla_resolution", "createdAt": "2026-09-29T08:12:44Z", "updatedAt": "2026-09-29T10:15:31Z", "completedAt": null, "links": [ { "type": "contact", "id": "77aa1c2d3e4f4a5b8c9d0e1f2a3b4c5d", "name": "Lucía Gómez" }, { "type": "conversation", "id": "c0de1c2d3e4f4a5b8c9d0e1f2a3b4c5d", "channel": "email" } ], "appUrl": "https://crm.example.com/app/tickets/9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "version": 18, "etag": "W/\"h:3fa9c2d17b0e4a55\"", "editable": [ "status", "sourceStatus", "assigneeId", "teamId", "priority", "title", "category" ], "actions": [ { "name": "resolve", "scope": "support:execute", "actor": "service", "available": true, "preview": false, "inputSchema": "/api/v1/task-kinds#support.ticket/resolve" }, { "name": "reply", "scope": "support:execute", "actor": "delegated", "available": false, "unavailableReason": "DELEGATED_USER_REQUIRED", "preview": false, "inputSchema": "/api/v1/task-kinds#support.ticket/reply" } ], "externalLink": { "externalId": "SUP-431", "url": "https://jira.example.com/browse/SUP-431" } } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:read of the kind) or FEATURE_DISABLED (api.tasks or the kind's feature).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Tasks" ], "summary": "Change a task", "description": "Change the fields the kind and its state admit with one internal call (`:write`; `If-Match` required).", "operationId": "updateTask", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source); another body is 409.", "title": "Idempotency-Key" }, "description": "1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source); another body is 409." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "es or en for generated titles.", "title": "Accept-Language" }, "description": "es or en for generated titles." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." } ], "responses": { "200": { "description": "The task after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTask" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:write, and the scope of the equivalent action when status changes), FEATURE_DISABLED, DELEGATED_USER_* or ACTOR_ROLE_INSUFFICIENT.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS, ACTION_OUTCOME_UNKNOWN, SEND_SWITCH_OFF or a code of the internal function (MERGED_RECORD…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, TASK_FIELD_NOT_SUPPORTED (supportedFields), TASK_STATUS_REQUIRES_ACTION (actions), TASK_PATCH_SPLIT_REQUIRED, IF_MATCH_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "Only the fields sent change; unknown fields are 422 FIELD_NOT_ALLOWED and fields the kind or state does not admit 422 TASK_FIELD_NOT_SUPPORTED.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "needs_review", "done", "cancelled" ] }, "sourceStatus": { "type": "string" }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "normal", "high", "urgent", null ] }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" }, "assigneeId": { "type": [ "string", "null" ], "description": "null removes the assignee." }, "teamId": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "activityKind": { "type": "string" }, "contactId": { "type": [ "string", "null" ] }, "dealId": { "type": [ "string", "null" ] }, "ticketId": { "type": [ "string", "null" ] } } }, "examples": { "reassign": { "summary": "Reassign and postpone a follow-up", "value": { "assigneeId": "3c1f2a9e-0000-4000-8000-000000000000", "dueAt": "2026-10-03T09:00:00Z" } } } } } } } }, "/api/v1/tasks/{task_id}/actions/{action}": { "post": { "tags": [ "Tasks" ], "summary": "Run an action of a task", "description": "Run an action of the task with the same function, validations and permissions as the UI. `dryRun` runs only\nthe native previous step or validates; `Idempotency-Key` is required otherwise.", "operationId": "runTaskAction", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" }, "examples": { "succeeded": { "summary": "resolve applied", "value": { "runId": "ar_5c0e1d2f3a4b4c5d8e9f0a1b2c3d4e5f", "taskId": "support.ticket:9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "action": "resolve", "dryRun": false, "outcome": "succeeded", "replayed": false, "result": { "ticketId": "9d2f4b1c0a7e4e21b3c5d6e7f8091a2b" }, "task": { "id": "support.ticket:9d2f4b1c0a7e4e21b3c5d6e7f8091a2b", "status": "done", "etag": "W/\"h:91b0c2d17b0e4a55\"" } } }, "dryRun": { "summary": "dryRun of an action with a native previous step", "value": { "dryRun": true, "valid": true, "taskId": "marketing.campaign:4e1a2b3c4d5e4f6a8b9c0d1e2f3a4b5c", "action": "schedule", "preview": { "totalRecipients": 1240, "blocked": 12 }, "confirm": { "audienceFingerprint": "9ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d7" } } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "complete": { "summary": "Complete (crm_activity.complete; activities:execute, service)", "value": { "input": {} } }, "mark_read": { "summary": "Mark as read (sales_conversation.mark_read; sequences:execute, service)", "value": { "input": {} } }, "mark_done": { "summary": "Mark as done (customer_message.mark_done; support:execute, service)", "value": { "input": {} } }, "resolve": { "summary": "Close a ticket from a tool transition", "value": { "input": {} } }, "preview": { "summary": "Two steps: dryRun returns the confirmation token", "value": { "dryRun": true, "input": {} } } } } } } } }, "/api/v1/tasks/{task_id}/external-link": { "put": { "tags": [ "Tasks" ], "summary": "Link a task to your tool", "description": "Keep your `externalId` and URL on the task, only for this source (scope `:write`).", "operationId": "putTaskExternalLink", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The link of this source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskExternalLink" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:write) or FEATURE_DISABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "EXTERNAL_ID_TAKEN: the externalId already links another task of this source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR, EXTERNAL_ID_INVALID, EXTERNAL_ID_EMAIL_SHAPE, EXTERNAL_ID_PHONE_SHAPE or EXTERNAL_LINK_URL_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "externalId", "url" ], "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Your ID: visible ASCII, never an email or a phone; one task per externalId and source." }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS, without credentials." } } }, "examples": { "jira": { "summary": "Link the task with its issue", "value": { "externalId": "SUP-431", "url": "https://jira.example.com/browse/SUP-431" } } } } } } }, "delete": { "tags": [ "Tasks" ], "summary": "Remove the link of a task", "description": "Remove the link of this source (scope `:write`).", "operationId": "deleteTaskExternalLink", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "204": { "description": "The link of this source is gone (or there was none)." }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:write) or FEATURE_DISABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/tasks/{task_id}/history": { "get": { "tags": [ "Tasks" ], "summary": "Read the history of a task", "description": "Date, type, actor and changed fields of the native history, without bodies (scope `:read`).", "operationId": "getTaskHistory", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 50, "title": "Limit" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Changes of the task: date, type, actor (user, api or system) and changed fields; never bodies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskHistory" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:read of the kind) or FEATURE_DISABLED (api.tasks or the kind's feature).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "TASK_FIELD_NOT_SUPPORTED: this kind has no native history.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/tasks/{task_id}/notes": { "get": { "tags": [ "Tasks" ], "summary": "Read the notes of a task", "description": "Native internal notes of the task (scope `:content`).", "operationId": "listTaskNotes", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Native notes of the task (support.ticket, sales.conversation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskNotes" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (the content scope of the area) or FEATURE_DISABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "TASK_FIELD_NOT_SUPPORTED: this kind has no native notes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Tasks" ], "summary": "Add a note to a task", "description": "Add a native internal note (scope `:write`, delegated user).", "operationId": "addTaskNote", "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Task Id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source); another body is 409.", "title": "Idempotency-Key" }, "description": "1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source); another body is 409." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "The note added through the same function as the UI. A retry with the same Idempotency-Key answers the same note (replayed: read again, or its ID, author, mentions and date when it can no longer be read).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskNoteAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (:write), FEATURE_DISABLED or DELEGATED_USER_* (notes need a delegated user).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND: it does not exist, belongs to another company or is no longer a task (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS or ACTION_OUTCOME_UNKNOWN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "TASK_FIELD_NOT_SUPPORTED, FIELD_NOT_ALLOWED or VALIDATION_ERROR (text of 1-5000 characters).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000 }, "mentionUserIds": { "type": "array", "maxItems": 20, "items": { "type": "string" } } } }, "examples": { "mention": { "summary": "An internal note that mentions a teammate", "value": { "text": "El cliente confirma que no le llega la factura; lo revisa Facturación.", "mentionUserIds": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] } } } } } } } }, "/api/v1/templates": { "get": { "tags": [ "Campaigns" ], "summary": "List email templates", "description": "Email templates of the company (scope `campaigns:read`).", "operationId": "listTemplates", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Email templates of the company.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMarketingTemplatePage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/templates/{template_id}": { "get": { "tags": [ "Campaigns" ], "summary": "Read an email template", "description": "One email template (scope `campaigns:read`).", "operationId": "getTemplate", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Template Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "One email template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiMarketingTemplate" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (campaigns:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TEMPLATE_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/tickets": { "get": { "tags": [ "Support" ], "summary": "List tickets", "description": "Support tickets, newest first, with a cursor (scope `support:read`); `assigneeId`, `sla` and `updatedSince` run\non the task index (seconds behind).", "operationId": "listTickets", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "all (default) or a native status: open, pending, waiting_customer, waiting_internal, paused or resolved.", "examples": [ "open" ], "title": "Status" }, "description": "all (default) or a native status: open, pending, waiting_customer, waiting_internal, paused or resolved." }, { "name": "teamId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tickets of this support team.", "title": "Teamid" }, "description": "Tickets of this support team." }, { "name": "contactId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tickets of this contact (an ID, never personal data).", "title": "Contactid" }, "description": "Tickets of this contact (an ID, never personal data)." }, { "name": "conversationId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The ticket of this conversation.", "title": "Conversationid" }, "description": "The ticket of this conversation." }, { "name": "pipelineId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tickets of this ticket pipeline.", "title": "Pipelineid" }, "description": "Tickets of this ticket pipeline." }, { "name": "assigneeId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Tickets of this assignee (task index).", "title": "Assigneeid" }, "description": "Tickets of this assignee (task index)." }, { "name": "sla", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "at_risk or breached: tickets with that SLA signal (task index).", "examples": [ "breached" ], "title": "Sla" }, "description": "at_risk or breached: tickets with that SLA signal (task index)." }, { "name": "updatedSince", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "RFC 3339: tickets whose observed change (task index) is at or after it.", "title": "Updatedsince" }, "description": "RFC 3339: tickets whose observed change (task index) is at or after it." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Tickets of the company, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicketPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "post": { "tags": [ "Support" ], "summary": "Create a ticket", "description": "Create a ticket of an existing contact through the same function as the UI (scope `support:write`;\n`Idempotency-Key` required).", "operationId": "createTicket", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required: 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit (428 IDEMPOTENCY_KEY_REQUIRED without it), per source. The same key and body return the first result for 7 days; another body is 409 IDEMPOTENCY_CONFLICT." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created through the same function as the UI (the case and its internal conversation).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicket" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the ticket; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } }, "Location": { "description": "URL of the new ticket (/api/v1/tickets/{id}).", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:write), FEATURE_DISABLED (api.tasks) or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "CONTACT_NOT_FOUND, TEAM_NOT_FOUND, STAGE_NOT_FOUND, PIPELINE_NOT_FOUND or TICKET_NOT_FOUND (parentId).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT (same Idempotency-Key, another body), IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN, MERGED_RECORD (canonicalId), ASSIGNEE_NOT_IN_TEAM, ASSIGNEE_AT_CAPACITY, TEAM_CHANNEL_MISMATCH or STAGE_ARCHIVED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED (contactName and other contact data are not accepted), VALIDATION_ERROR (field) or ASSIGNEE_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "title", "contactId" ], "description": "A ticket of an existing contact (create contacts with POST /api/v1/contacts).", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 20000 }, "category": { "type": "string", "maxLength": 100 }, "contactId": { "type": "string", "maxLength": 64 }, "teamId": { "type": [ "string", "null" ], "maxLength": 64 }, "assigneeId": { "type": [ "string", "null" ], "maxLength": 64 }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "pipelineId": { "type": [ "string", "null" ], "maxLength": 64 }, "stageId": { "type": [ "string", "null" ], "maxLength": 64 }, "parentId": { "type": [ "string", "null" ], "maxLength": 64 }, "customValues": { "type": "object" } } }, "examples": { "ticket": { "summary": "A ticket from the tool", "value": { "title": "No llega la factura de septiembre", "contactId": "77aa0000-0000-4000-8000-000000000000", "priority": "high", "category": "Facturación" } } } } } } } }, "/api/v1/tickets/search": { "post": { "tags": [ "Support" ], "summary": "Search tickets", "description": "The ticket list with a text search in the body (`q`): never in the URL (scope `support:read`).", "operationId": "searchTickets", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Tickets matching the search, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicketPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Title and, when the source may read names, the name of the contact if the source reaches it (contactScope)." }, "status": { "type": "string", "enum": [ "open", "pending", "waiting_customer", "waiting_internal", "paused", "resolved", "all" ] }, "teamId": { "type": "string" }, "contactId": { "type": "string" }, "conversationId": { "type": "string" }, "pipelineId": { "type": "string" }, "assigneeId": { "type": "string", "description": "From the task index." }, "sla": { "type": "string", "enum": [ "at_risk", "breached" ], "description": "From the task index." }, "updatedSince": { "type": "string", "format": "date-time", "description": "Observed changes (task index)." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string" } } }, "examples": { "title": { "summary": "Open tickets about invoices", "value": { "q": "factura", "status": "open" } } } } } } } }, "/api/v1/tickets/{resource_id}/actions/{action}": { "post": { "tags": [ "Support" ], "summary": "Run an action of a ticket", "description": "Run an action of a tickets resource: the same action, checks and idempotency as the task action (`dryRun`, `Idempotency-Key`).", "operationId": "runTicketAction", "parameters": [ { "name": "resource_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Resource Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "add_note": { "summary": "Add an internal note (support_case.add_note; support:write, delegated)", "value": { "input": { "text": "Lo revisa Facturación esta tarde.", "mentionUserIds": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] } } }, "apply_macro": { "summary": "Apply a macro (support_case.apply_macro; support:execute, delegated)", "value": { "input": { "macroId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "previewToken": "9ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d79ab3c4d5e6f7a8b9c0d1e2f3a4b5c6d7" } } }, "apply_macro.dryRun": { "summary": "Apply a macro: dryRun returns the confirmation token(s) previewToken", "value": { "dryRun": true, "input": { "macroId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "assign": { "summary": "Assign (support_case.assign; support:execute, service)", "value": { "input": { "assigneeId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "hand_off": { "summary": "Hand off to a person (support_case.hand_off; support:execute, service)", "value": { "input": {} } }, "mark_read": { "summary": "Mark as read (support_case.mark_read; support:execute, service)", "value": { "input": {} } }, "merge_into": { "summary": "Merge into another ticket (support_case.merge_into; support:execute, service)", "value": { "input": { "targetTicketId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "public_reply": { "summary": "Public reply on the portal (support_case.public_reply; support:execute, delegated)", "value": { "input": { "text": "Hola Lucía, ya hemos reenviado la factura de septiembre." } } }, "reopen": { "summary": "Reopen (support_case.reopen; support:execute, service)", "value": { "input": {} } }, "reply": { "summary": "Reply to the customer (support_case.reply; support:execute, delegated)", "value": { "input": { "text": "Hola Lucía, ya hemos reenviado la factura de septiembre.", "expectedLastMessageId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "resolve": { "summary": "Resolve (support_case.resolve; support:execute, service)", "value": { "input": {} } }, "return_to_ai": { "summary": "Return to the AI (support_case.return_to_ai; support:execute, service)", "value": { "input": {} } }, "set_labels": { "summary": "Set labels (support_case.set_labels; support:write, service)", "value": { "input": { "labelIds": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] } } }, "set_stage": { "summary": "Change stage (support_case.set_stage; support:write, service)", "value": { "input": { "stageId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "set_status": { "summary": "Change status (support_case.set_status; support:execute, service)", "value": { "input": { "sourceStatus": "waiting_customer" } } }, "set_team": { "summary": "Change team (support_case.set_team; support:write, service)", "value": { "input": { "teamId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" } } }, "snooze": { "summary": "Snooze (support_case.snooze; support:execute, delegated)", "value": { "input": { "until": "2026-10-01T09:00:00Z" } } }, "split": { "summary": "Split (support_case.split; support:execute, service)", "value": { "input": { "title": "Segunda factura duplicada" } } }, "unsnooze": { "summary": "Wake up now (support_case.unsnooze; support:execute, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/tickets/{ticket_id}": { "get": { "tags": [ "Support" ], "summary": "Read a ticket", "description": "A ticket with its SLA, task status, signals and `ETag` (scope `support:read`).", "operationId": "getTicket", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The ticket with its SLA and ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicket" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the ticket; send it back as If-Match.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TICKET_NOT_FOUND: it does not exist, belongs to another company or is a sales conversation (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } }, "patch": { "tags": [ "Support" ], "summary": "Update a ticket", "description": "Change a ticket with one call to the ticket update of the UI (scope `support:write`, `support:execute` for the\nstatus) and optimistic concurrency (`If-Match`).", "operationId": "updateTicket", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } }, { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Required: the ETag you read (W/\"3\" or W/\"h:…\"). Without it 428 PRECONDITION_REQUIRED; when it is not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source).", "title": "Idempotency-Key" }, "description": "Optional: 1-200 of A-Z a-z 0-9 . _ : ~ -. The same key and body never run twice (7 days, per source)." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The ticket after the change, with its new ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicket" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the ticket; send it back as If-Match.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:write; support:execute to change the status), FEATURE_DISABLED or DELEGATED_USER_*.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TICKET_NOT_FOUND: it does not exist, belongs to another company or is a sales conversation (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS, ACTION_OUTCOME_UNKNOWN, TICKET_MERGED, ASSIGNEE_NOT_IN_TEAM, ASSIGNEE_AT_CAPACITY, TEAM_CHANNEL_MISMATCH or PIPELINE_STAGE_MISSING.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: If-Match is not the current ETag (currentEtag and the ETag header): read and retry.", "headers": { "ETag": { "description": "W/\"h:<16 hex>\" of the ticket; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, TASK_FIELD_NOT_SUPPORTED (supportedFields), TASK_STATUS_REQUIRES_ACTION (actions), VALIDATION_ERROR (sourceStatus needs status and must belong to it), ASSIGNEE_INVALID or IF_MATCH_INVALID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "PRECONDITION_REQUIRED: send If-Match with the ETag you read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "description": "The task PATCH of support.ticket: one call to the ticket update of the UI. Changing status also needs support:execute; send If-Match with the ETag you read.", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "category": { "type": "string", "minLength": 1, "maxLength": 80 }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "assigneeId": { "type": [ "string", "null" ], "maxLength": 64, "description": "null removes the assignee." }, "teamId": { "type": [ "string", "null" ], "maxLength": 64, "description": "null removes the team." }, "status": { "type": "string", "enum": [ "open", "waiting", "done" ] }, "sourceStatus": { "type": "string", "enum": [ "open", "pending", "waiting_customer", "waiting_internal", "paused", "resolved" ], "description": "Needs status: open (open, pending), waiting (waiting_customer, waiting_internal, paused) or done (resolved)." } } }, "examples": { "waiting": { "summary": "Wait for the customer", "value": { "status": "waiting", "sourceStatus": "waiting_customer" } }, "assign": { "summary": "Reassign and change the priority", "value": { "assigneeId": "3c1f2a9e-0000-4000-8000-000000000000", "priority": "urgent" } } } } } } } }, "/api/v1/tickets/{ticket_id}/events": { "get": { "tags": [ "Support" ], "summary": "Read the events of a ticket", "description": "The ticket's history (scope `support:read`); bodies and values with `include=body` (`support:content`).", "operationId": "listTicketEvents", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } }, { "name": "include", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "body: bodies and values of the events (needs support:content).", "examples": [ "body" ], "title": "Include" }, "description": "body: bodies and values of the events (needs support:content)." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Events of the ticket: actor, type and changed fields; bodies and values only with include=body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicketEvents" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read; support:content for include=body) or FEATURE_DISABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TICKET_NOT_FOUND: it does not exist, belongs to another company or is a sales conversation (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/tickets/{ticket_id}/files": { "get": { "tags": [ "Support" ], "summary": "List the attachments of a ticket", "description": "Metadata of the ticket's attachments (scope `support:read`). Uploading stays in the app.", "operationId": "listTicketFiles", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Metadata of the attachments (never their content).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTicketFiles" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TICKET_NOT_FOUND: it does not exist, belongs to another company or is a sales conversation (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/tickets/{ticket_id}/files/{file_id}": { "get": { "tags": [ "Support" ], "summary": "Download an attachment of a ticket", "description": "One attachment, always as a download (scopes `support:read` and `support:content`).", "operationId": "downloadTicketFile", "parameters": [ { "name": "ticket_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Ticket Id" } }, { "name": "file_id", "in": "path", "required": true, "schema": { "type": "string", "title": "File Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The attachment, always as a download (application/octet-stream).", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (support:read and support:content) or FEATURE_DISABLED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TICKET_NOT_FOUND or FILE_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED (a search term or personal data in the URL) or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/voice/calls": { "get": { "tags": [ "Voice" ], "summary": "List calls", "description": "Phone calls, newest first, with the tasks they generate (scope `voice:read`); the summary only with\n`voice:content`; never the recording.", "operationId": "listVoiceCalls", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Calls, newest first; the summary only with voice:content; never the recording.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVoiceCallPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (voice:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/voice/calls/{call_id}": { "get": { "tags": [ "Voice" ], "summary": "Read a call", "description": "A call with its jobs and `ETag` (scope `voice:read`); summary and transcript only with `voice:content`; never the\nrecording.", "operationId": "getVoiceCall", "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The call with its jobs and, with voice:content, its summary and transcript; never the recording.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVoiceCall" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "ETag": { "description": "W/\"h:<16 hex>\" of the call.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (voice:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "VOICE_CALL_NOT_FOUND: it does not exist or belongs to another company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/voice/calls/{call_id}/actions/{action}": { "post": { "tags": [ "Voice" ], "summary": "Run an action of a call", "description": "email_summary (scope `voice:execute`, delegated user): the same checks, `dryRun` and idempotency as a task\naction.", "operationId": "runVoiceCallAction", "parameters": [ { "name": "call_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Call Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "email_summary": { "summary": "Email the summary (voice_call.email_summary; voice:execute, delegated)", "value": { "input": { "emailAccountId": "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40", "recipient": "ana@example.com" } } } } } } } } }, "/api/v1/voice/capacity": { "get": { "tags": [ "Voice" ], "summary": "Read the call capacity", "description": "The company's concurrent call capacity and the calls to review (scope `voice:read`).", "operationId": "getVoiceCapacity", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The concurrent call capacity and the calls to review.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVoiceCapacity" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (voice:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/voice/capacity/{reservation_id}/actions/{action}": { "post": { "tags": [ "Voice" ], "summary": "Review a call of the capacity", "description": "review (scope `voice:admin`, delegated administrator): the same checks, `dryRun` and idempotency as the task\naction.", "operationId": "runVoiceCapacityAction", "parameters": [ { "name": "reservation_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Reservation Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "review": { "summary": "Review with the provider (voice_capacity_reservation.review; voice:admin, delegated)", "value": { "input": {} } } } } } } } }, "/api/v1/voice/jobs": { "get": { "tags": [ "Voice" ], "summary": "List voice jobs", "description": "Jobs of the calls (failed and uncertain by default), newest first, with their task (scope `voice:read`).", "operationId": "listVoiceJobs", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated job statuses (failed,uncertain by default; pending, running, done, cancelled).", "examples": [ "failed,uncertain" ], "title": "Status" }, "description": "Comma separated job statuses (failed,uncertain by default; pending, running, done, cancelled)." }, { "name": "kind", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma separated kinds: summary, recording, email or agent.", "examples": [ "email" ], "title": "Kind" }, "description": "Comma separated kinds: summary, recording, email or agent." }, { "name": "callId", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The jobs of this call.", "title": "Callid" }, "description": "The jobs of this call." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Voice jobs (failed and uncertain by default), newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiVoiceJobPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (voice:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/voice/jobs/{job_id}/actions/{action}": { "post": { "tags": [ "Voice" ], "summary": "Run an action of a voice job", "description": "retry (scope `voice:execute`; `confirmPossibleDuplicate` for an uncertain job; never an assistant turn): the same\nchecks, `dryRun` and idempotency as the task action.", "operationId": "runVoiceJobAction", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } }, { "name": "action", "in": "path", "required": true, "schema": { "type": "string", "title": "Action" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "examples": [ "jira-SUP-431-transition-51" ], "pattern": "^[A-Za-z0-9][A-Za-z0-9._:~\\-]{0,199}$" }, "description": "Required unless dryRun is true (428 IDEMPOTENCY_KEY_REQUIRED): 1-200 of A-Z a-z 0-9 . _ : ~ - starting with a letter or digit, per source.The same key and body replay the first answer for 7 days (Idempotent-Replayed: true); another body is 409 IDEMPOTENCY_CONFLICT; a run interrupted with an unknown outcome is 409 ACTION_OUTCOME_UNKNOWN and is never repeated by RouterClip. Use the ID of the event of your tool (changelog, comment, transition).", "x-aio-required": "unless dryRun" }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^\\s*(W/)?\"(\\d{1,12}|h:[0-9a-f]{16})\"\\s*$", "examples": [ "W/\"7\"", "W/\"h:3fa9c2d17b0e4a55\"" ] }, "description": "Optional: the ETag you read (W/\"3\" or W/\"h:…\"); when sent and not the current one, 412 REVISION_CONFLICT with currentEtag." }, { "name": "X-AIO-Act-As", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64, "examples": [ "3c1f2a9e0b7d4c1e9f3a5b7c9d1e2f40" ] }, "description": "ID of a user of the source's delegation list to act as (needs the act_as scope; 403 DELEGATED_USER_NOT_ALLOWED or DELEGATED_USER_INACTIVE otherwise). Without it the source's default user acts, if any; operations of the service identity run without a user. Actions that talk to a customer, notes with mentions, macros and every admin-level action need a delegated user (DELEGATED_USER_REQUIRED, ACTOR_ROLE_INSUFFICIENT)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "succeeded (the effect is applied), a dryRun answer, or the replay of the same request (replayed, Idempotent-Replayed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } } }, "202": { "description": "accepted: the internal function only queued the work; the task changes when it finishes.", "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "true when this answer replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskActionAnswer" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED, FEATURE_DISABLED, DELEGATED_USER_REQUIRED, DELEGATED_USER_NOT_ALLOWED, DELEGATED_USER_INACTIVE, ACTOR_ROLE_INSUFFICIENT or MAILBOX_OWNER_REQUIRED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "TASK_NOT_FOUND (or RESOURCE_NOT_FOUND) or TASK_ACTION_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "TASK_ACTION_NOT_AVAILABLE (reason, status), SEND_SWITCH_OFF, IDEMPOTENCY_CONFLICT, IDEMPOTENCY_IN_PROGRESS (Retry-After), ACTION_OUTCOME_UNKNOWN (read the task before deciding; never repeated) or a code of the internal function (MERGE_PREVIEW_STALE, OUTBOUND_UNCERTAIN…).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "412": { "description": "REVISION_CONFLICT: the If-Match sent is not the current ETag.", "headers": { "ETag": { "description": "W/\"\" or W/\"h:<16 hex>\" of the live task; send it back as If-Match.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field input.…; confirmation_required when the dryRun token is missing), IF_MATCH_INVALID, IDEMPOTENCY_KEY_INVALID or a code of the internal function.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "428": { "description": "IDEMPOTENCY_KEY_REQUIRED (not for dryRun).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "input": { "type": "object", "description": "Matches the action's inputSchema in GET /api/v1/task-kinds." }, "dryRun": { "type": "boolean", "default": false, "description": "Run only the native previous step (its token comes back in confirm) or validate; nothing is executed and no Idempotency-Key is needed." } } }, "examples": { "retry": { "summary": "Retry (voice_job.retry; voice:execute, service)", "value": { "input": { "confirmPossibleDuplicate": true } } } } } } } } }, "/api/v1/web-forms": { "get": { "tags": [ "Forms" ], "summary": "List the web forms", "description": "The forms of the company's own websites with their counts, never their submissions (scope `forms:read`).", "operationId": "listWebForms", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "nextCursor of the previous page (same filters).", "title": "Cursor" }, "description": "nextCursor of the previous page (same filters)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Forms of the company's websites (no submissions).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiWebFormPage" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "400": { "description": "CURSOR_INVALID: altered, expired or made for another source or other filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (forms:read) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "QUERY_PARAMETER_NOT_ALLOWED or VALIDATION_ERROR (field).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List the task webhooks", "description": "The task webhooks of **this key's source** (scope `webhooks:manage`, feature `api.tasks`), the limits and whether\nthe platform sends them now.", "operationId": "listTaskWebhooks", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The task webhooks of this key's source.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhookList" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create a task webhook", "description": "Register an HTTPS endpoint that receives `task.created`, `task.updated`, `task.completed` and `task.deleted`\n(up to 5 per source and 20 per company). Every POST is signed: `X-CRM-Signature: sha256=HMAC(secret,\n\"..\")`; deduplicate by `X-CRM-Delivery-Id`, discard a `version` you\nalready know and answer 2xx within 10 s. The body carries IDs and statuses only: read the change feed or the task.\nThe secret comes **only** in this answer.", "operationId": "createTaskWebhook", "parameters": [ { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "201": { "description": "Created; the answer carries the secret (whsec_…) once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhookWithSecret" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "WEBHOOK_LIMIT (limit, per: 5 per source, 20 per company).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), WEBHOOK_URL_INVALID, WEBHOOK_URL_NOT_AUTHORIZED (the platform has not authorized the origin) or WEBHOOK_KIND_NOT_READABLE (kinds this key cannot read).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "503": { "description": "SECRET_STORE_UNAVAILABLE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "name", "url" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS on port 443, without credentials or fragment, on an origin the platform authorized." }, "kinds": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "Task kinds this key can read; empty (default) means all of them." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "task.created", "task.updated", "task.completed", "task.deleted" ] }, "minItems": 1, "description": "All four by default." }, "skipOwnChanges": { "type": "boolean", "default": true }, "enabled": { "type": "boolean", "default": true } } }, "examples": { "tickets": { "summary": "Wake the tool when a ticket or a follow-up changes", "value": { "name": "Jira Support", "url": "https://hooks.example.com/routerclip", "kinds": [], "events": [ "task.created", "task.updated", "task.completed", "task.deleted" ], "skipOwnChanges": true } } } } } } } }, "/api/v1/webhooks/{webhook_id}": { "get": { "tags": [ "Webhooks" ], "summary": "Read a task webhook", "description": "One task webhook of this key's source, without its secret.", "operationId": "getTaskWebhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The task webhook, without its secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhook" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another source or company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Change a task webhook", "description": "Change name, URL, kinds, events, `skipOwnChanges` or `enabled`. Disabling closes its queue; enabling again\nchecks that the platform still authorizes the origin.", "operationId": "updateTaskWebhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The task webhook after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhook" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another source or company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "413": { "description": "Body above 32 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "415": { "description": "UNSUPPORTED_MEDIA_TYPE: send Content-Type: application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "FIELD_NOT_ALLOWED, VALIDATION_ERROR (field), WEBHOOK_URL_INVALID, WEBHOOK_URL_NOT_AUTHORIZED (the platform has not authorized the origin) or WEBHOOK_KIND_NOT_READABLE (kinds this key cannot read).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS on port 443, without credentials or fragment, on an origin the platform authorized." }, "kinds": { "type": "array", "maxItems": 50, "items": { "type": "string" }, "description": "Task kinds this key can read; empty (default) means all of them." }, "events": { "type": "array", "items": { "type": "string", "enum": [ "task.created", "task.updated", "task.completed", "task.deleted" ] }, "minItems": 1, "description": "All four by default." }, "skipOwnChanges": { "type": "boolean", "default": true }, "enabled": { "type": "boolean", "default": true } }, "description": "Only the fields sent change; null is not accepted." }, "examples": { "pause": { "summary": "Stop deliveries for a while", "value": { "enabled": false } }, "kinds": { "summary": "Only tickets and follow-ups", "value": { "kinds": [ "support.ticket", "crm.activity" ] } } } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a task webhook", "description": "Delete a task webhook of this key's source and its deliveries.", "operationId": "deleteTaskWebhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "204": { "description": "Deleted with its deliveries." }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another source or company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/webhooks/{webhook_id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List the deliveries of a task webhook", "description": "Status, attempts and last answer of each delivery, newest first (delivered kept 30 days, failed 90).", "operationId": "listTaskWebhookDeliveries", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "queued, sending, delivered or failed.", "examples": [ "failed" ], "title": "Status" }, "description": "queued, sending, delivered or failed." }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "1-100 (50 by default).", "examples": [ "50" ], "title": "Limit" }, "description": "1-100 (50 by default)." }, { "name": "offset", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "0-10000 (0 by default).", "examples": [ "0" ], "title": "Offset" }, "description": "0-10000 (0 by default)." }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "Deliveries of the webhook, newest first; never their body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhookDeliveries" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another source or company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "VALIDATION_ERROR (status, limit or offset).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } } } } }, "/api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry a failed delivery", "description": "Queue a failed delivery again with a new series of attempts (same delivery ID).", "operationId": "retryTaskWebhookDelivery", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "delivery_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Delivery Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The delivery, queued again with a new series of attempts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhookDelivery" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND or WEBHOOK_DELIVERY_NOT_FOUND.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "WEBHOOK_DELIVERY_NOT_RETRYABLE (reason: status or disabled) or WEBHOOK_URL_NOT_AUTHORIZED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/webhooks/{webhook_id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the secret of a task webhook", "description": "A new `whsec_…` secret, shown only in this answer; the old one stops signing at once.", "operationId": "rotateTaskWebhookSecret", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "200": { "description": "The new secret, once; the old one stops signing at once.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhookWithSecret" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another source or company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "503": { "description": "SECRET_STORE_UNAVAILABLE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/webhooks/{webhook_id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test ping", "description": "Queue a signed `ping` (`{\"type\": \"ping\", \"data\": {\"endpointId\", \"sourceId\"}}`), sent like any delivery.", "operationId": "testTaskWebhook", "parameters": [ { "name": "webhook_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Webhook Id" } }, { "name": "X-Request-ID", "in": "header", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Optional correlation ID echoed in the answer.", "title": "X-Request-Id" }, "description": "Optional correlation ID echoed in the answer." } ], "responses": { "202": { "description": "A signed ping is queued (an unsent one is reused).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskWebhookTest" } } }, "headers": { "X-Request-ID": { "description": "Your valid X-Request-ID (8-128 of A-Z a-z 0-9 . _ : -) or a new one; quote it to support.", "schema": { "type": "string" } } } }, "401": { "description": "Missing, invalid, expired or revoked key, disabled source or inactive company: API_KEY_INVALID, API_KEY_EXPIRED, API_KEY_REVOKED, API_SOURCE_DISABLED, COMPANY_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "402": { "description": "The company has no service access (SUBSCRIPTION_PAYMENT_REQUIRED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "429": { "description": "Quota reached before anything ran: RATE_LIMITED (quota key, company or action: 60 writes and actions per minute and key, dryRun included) or API_AUTH_THROTTLED.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "403": { "description": "API_SCOPE_REQUIRED (webhooks:manage) or FEATURE_DISABLED (api.tasks).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "404": { "description": "WEBHOOK_NOT_FOUND: it does not exist or belongs to another source or company (the same answer).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "409": { "description": "WEBHOOK_DISABLED or WEBHOOK_URL_NOT_AUTHORIZED.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiTaskError" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ApiActivity": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string", "description": "crm.activity:." }, "title": { "type": "string" }, "description": { "type": "string", "description": "Internal details of the follow-up (never a customer's message)." }, "activityKind": { "type": "string", "enum": [ "task", "call", "email", "meeting" ] }, "status": { "type": "string", "enum": [ "open", "done", "cancelled" ] }, "priority": { "type": "string", "enum": [ "normal", "high" ] }, "dueAt": { "type": "string", "format": "date-time" }, "overdue": { "type": "boolean" }, "assigneeId": { "type": [ "string", "null" ] }, "assigneeName": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "contactName": { "type": [ "string", "null" ], "description": "Only when the source may read the name and reaches the contact." }, "dealId": { "type": [ "string", "null" ] }, "dealTitle": { "type": [ "string", "null" ] }, "ticketId": { "type": [ "string", "null" ] }, "ticketTitle": { "type": [ "string", "null" ] }, "originType": { "type": [ "string", "null" ], "enum": [ "manual", "sequence", "playbook", "api", "assignment", "journey", "process", "approval", "scoring", "sales_reply", "assistant", "quote", "contract", "meeting", "flow", null ], "description": "What created the follow-up (null when it was not recorded). manual: created by a person in the app; sequence: a task step of a sales sequence (originId: the step execution, or meeting:); playbook: the next activity of a playbook session (originId: the session step); api: created through /api/v1 (originId: the API source); assignment: an assignment rule (originId: the rule); journey: an action of a marketing journey (originId: the action log); process: a step of a deal process (originId: the process step); approval: the task of an approver of a stage approval (originId: the request); while it is pending it is decided, not completed or moved by hand (422 APPROVAL_DECISION_REQUIRED); scoring: the alert of a contact that reached a priority grade (originId: the contact); sales_reply: the triage of a sales reply (originId: the triage); assistant: an AI assistant suggestion accepted by a person (originId: the suggestion); quote: the follow-up of a quote (originId: the quote); contract: a support contract (originId: the contract); meeting: a calendar booking that became confirmed (originId: the booking); cancelled with the booking; flow: a step of an automation flow (originId: the run step), or the notice of a flow paused by a limit (originId: the flow)." }, "originId": { "type": [ "string", "null" ] }, "createdById": { "type": [ "string", "null" ] }, "completedById": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer", "description": "The ETag is W/\"\"." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks of the follow-up (its own)." } }, "type": "object", "required": [ "id", "taskId", "title", "activityKind", "status", "priority", "dueAt", "revision", "taskIds" ], "title": "ApiActivity", "description": "A CRM follow-up (its task is crm.activity:). The ETag is W/\"\"." }, "ApiActivityHistory": { "properties": { "activityId": { "type": "string" }, "taskId": { "type": "string" }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "type": { "type": "string", "enum": [ "created", "status_changed", "rescheduled", "reassigned", "relinked", "updated" ] }, "revision": { "type": "integer" }, "actor": { "properties": { "kind": { "type": "string", "enum": [ "user", "api", "system" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "changedFields": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array", "description": "Newest first; never the description or values." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "activityId", "items", "nextCursor", "hasMore" ], "title": "ApiActivityHistory" }, "ApiActivityPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiActivity" }, "type": "array", "description": "By due date." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiActivityPage" }, "ApiAutomationEnrollResult": { "properties": { "result": { "type": "string", "enum": [ "started", "skipped" ], "description": "started is not done: the worker runs the steps with every check of the engine." }, "runId": { "type": "string", "description": "Only with result started." }, "reason": { "type": "string", "enum": [ "flowNotActive", "subjectUnavailable", "conditionsNotMet", "activeRunExists", "alreadyRan", "cooldown", "entryLimitReached" ], "description": "Only with result skipped." }, "flowId": { "type": "string" }, "subject": { "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "type": "object" } }, "type": "object", "required": [ "result", "flowId", "subject" ], "title": "ApiAutomationEnrollResult" }, "ApiAutomationFlow": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "subjectType": { "type": "string", "enum": [ "contact", "deal", "conversation" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "trigger": { "properties": { "type": { "type": "string" } }, "type": [ "object", "null" ], "description": "The trigger type of the version in use (api for flows started with POST …/enroll); never its options." }, "publishedVersion": { "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": [ "object", "null" ] }, "enrollable": { "type": "boolean", "description": "Active and with the API trigger: POST …/enroll can start it." }, "pauseReason": { "type": [ "string", "null" ], "enum": [ "manual", "limit", null ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "runs": { "properties": { "live": { "type": "integer" }, "paused": { "type": "integer" }, "failed": { "type": "integer" } }, "type": "object", "description": "Live runs (active, waiting, processing or paused), paused and failed ones." } }, "type": "object", "required": [ "id", "name", "subjectType", "status", "enrollable" ], "title": "ApiAutomationFlow", "description": "A flow without its definition (ARQ-G10)." }, "ApiAutomationFlowPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "subjectType": { "type": "string", "enum": [ "contact", "deal", "conversation" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "trigger": { "properties": { "type": { "type": "string" } }, "type": [ "object", "null" ], "description": "The trigger type of the version in use (api for flows started with POST …/enroll); never its options." }, "publishedVersion": { "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": [ "object", "null" ] }, "enrollable": { "type": "boolean", "description": "Active and with the API trigger: POST …/enroll can start it." }, "pauseReason": { "type": [ "string", "null" ], "enum": [ "manual", "limit", null ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "runs": { "properties": { "live": { "type": "integer" }, "paused": { "type": "integer" }, "failed": { "type": "integer" } }, "type": "object", "description": "Live runs (active, waiting, processing or paused), paused and failed ones." } }, "type": "object", "required": [ "id", "name", "subjectType", "status", "enrollable" ], "description": "A flow without its definition (ARQ-G10)." }, "type": "array" }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "hasMore" ], "title": "ApiAutomationFlowPage" }, "ApiAutomationRun": { "properties": { "id": { "type": "string" }, "flowId": { "type": "string" }, "versionId": { "type": "string" }, "version": { "type": [ "integer", "null" ] }, "subject": { "properties": { "type": { "type": "string", "enum": [ "contact", "deal", "conversation" ] }, "id": { "type": "string" } }, "type": "object" }, "status": { "type": "string", "enum": [ "active", "waiting", "processing", "paused", "completed", "exited", "failed", "cancelled" ] }, "currentStepId": { "type": [ "string", "null" ] }, "nextRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "triggerEventId": { "type": [ "string", "null" ], "description": "The fact that started it (an id of GET /api/v1/events); null when it started through the API." }, "entry": { "properties": { "type": { "type": "string" }, "dealId": { "type": "string" }, "conversationId": { "type": "string" } }, "type": "object" }, "wait": { "properties": { "kind": { "type": "string", "enum": [ "wait", "waitUntil", "waitForEvent" ] }, "until": { "type": [ "string", "null" ], "format": "date-time" } }, "type": [ "object", "null" ] }, "goalReached": { "type": "boolean" }, "errorCode": { "type": [ "string", "null" ] }, "endReason": { "type": [ "string", "null" ], "enum": [ "completed", "goal", "exitConditions", "subjectUnavailable", "flowArchived", "cancelled", "failed", "leaseExpired", "companyDeletion", null ] }, "stepsRun": { "type": "integer" }, "causalDepth": { "type": "integer" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "flow": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "subjectType": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only in the detail." }, "steps": { "items": { "properties": { "stepId": { "type": "string" }, "stepType": { "type": "string" }, "position": { "type": "integer" }, "status": { "type": "string", "enum": [ "done", "skipped", "failed", "paused" ] }, "resultCode": { "type": [ "string", "null" ] }, "effect": { "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ], "description": "The record the step created or changed (task, deal, note…)." }, "attempts": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Only in the detail." } }, "type": "object", "required": [ "id", "flowId", "subject", "status" ], "title": "ApiAutomationRun" }, "ApiAutomationRunPage": { "properties": { "flowId": { "type": "string" }, "items": { "items": { "properties": { "id": { "type": "string" }, "flowId": { "type": "string" }, "versionId": { "type": "string" }, "version": { "type": [ "integer", "null" ] }, "subject": { "properties": { "type": { "type": "string", "enum": [ "contact", "deal", "conversation" ] }, "id": { "type": "string" } }, "type": "object" }, "status": { "type": "string", "enum": [ "active", "waiting", "processing", "paused", "completed", "exited", "failed", "cancelled" ] }, "currentStepId": { "type": [ "string", "null" ] }, "nextRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "triggerEventId": { "type": [ "string", "null" ], "description": "The fact that started it (an id of GET /api/v1/events); null when it started through the API." }, "entry": { "properties": { "type": { "type": "string" }, "dealId": { "type": "string" }, "conversationId": { "type": "string" } }, "type": "object" }, "wait": { "properties": { "kind": { "type": "string", "enum": [ "wait", "waitUntil", "waitForEvent" ] }, "until": { "type": [ "string", "null" ], "format": "date-time" } }, "type": [ "object", "null" ] }, "goalReached": { "type": "boolean" }, "errorCode": { "type": [ "string", "null" ] }, "endReason": { "type": [ "string", "null" ], "enum": [ "completed", "goal", "exitConditions", "subjectUnavailable", "flowArchived", "cancelled", "failed", "leaseExpired", "companyDeletion", null ] }, "stepsRun": { "type": "integer" }, "causalDepth": { "type": "integer" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "flow": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "subjectType": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only in the detail." }, "steps": { "items": { "properties": { "stepId": { "type": "string" }, "stepType": { "type": "string" }, "position": { "type": "integer" }, "status": { "type": "string", "enum": [ "done", "skipped", "failed", "paused" ] }, "resultCode": { "type": [ "string", "null" ] }, "effect": { "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ], "description": "The record the step created or changed (task, deal, note…)." }, "attempts": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Only in the detail." } }, "type": "object", "required": [ "id", "flowId", "subject", "status" ] }, "type": "array" }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "flowId", "items", "total", "hasMore" ], "title": "ApiAutomationRunPage" }, "ApiBookingPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ], "description": "Only when the booking is a task." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", "cancelled", null ] }, "signals": { "items": { "type": "string", "enum": [ "uncertain", "overdue" ] }, "type": "array" }, "calendarId": { "type": "string" }, "calendarName": { "type": "string" }, "timeZone": { "type": "string" }, "start": { "type": [ "string", "null" ], "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "requesting", "confirmed", "cancelled", "superseded", "expired" ] }, "conversationId": { "type": "string" }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of reconcile." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." }, "guestName": { "type": "string", "description": "Only when the source may read names and reaches the contact (contactScope)." }, "guestEmail": { "type": "string", "description": "Only when the source may read emails and reaches the contact (contactScope)." } }, "type": "object", "required": [ "id", "calendarId", "start", "end", "status", "etag", "actions" ], "description": "A booking of a company calendar. While the provider has not confirmed it (requesting) its task is calendar.booking:." }, "type": "array", "description": "Unconfirmed first, then newest (the app's list, up to 200)." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiBookingPage" }, "ApiCalendarAvailability": { "properties": { "calendarId": { "type": "string" }, "name": { "type": "string" }, "timeZone": { "type": "string" }, "from": { "type": [ "string", "null" ], "format": "date-time" }, "to": { "type": [ "string", "null" ], "format": "date-time" }, "slots": { "items": { "properties": { "start": { "type": [ "string", "null" ], "format": "date-time" }, "end": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "calendarId", "from", "to", "slots" ], "title": "ApiCalendarAvailability", "description": "Free slots of a calendar between from and to (at most 14 days)." }, "ApiCalendarPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "timeZone": { "type": "string" }, "durationMinutes": { "type": "integer" }, "minNoticeMinutes": { "type": "integer" }, "weekdays": { "items": { "type": "integer" }, "type": "array", "description": "0 = Monday." }, "startHour": { "type": "integer" }, "endHour": { "type": "integer" }, "agentTypes": { "items": { "type": "string" }, "type": "array" }, "sequenceBookable": { "type": "boolean" }, "connectionStatus": { "type": "string" } }, "type": "object", "required": [ "id", "name", "enabled", "connectionStatus" ], "description": "A company calendar: schedule settings only (never the provider's calendar ID or the account)." }, "type": "array", "description": "By name." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiCalendarPage" }, "ApiCampaign": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ], "description": "marketing.campaign: (null for journey sends and subscription confirmations)." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "open", "in_progress", "waiting", "needs_review", "done", "cancelled", null ] }, "signals": { "items": { "type": "string", "enum": [ "error" ] }, "type": "array" }, "name": { "type": "string" }, "channel": { "type": "string", "enum": [ "email", "sms", "push" ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "running", "paused", "completed", "cancelled" ] }, "purpose": { "type": "string" }, "connectionId": { "type": [ "string", "null" ] }, "segmentId": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "body": { "type": "string" }, "filters": { "type": [ "object", "null" ] }, "content": { "type": [ "object", "null" ] }, "trackOpens": { "type": [ "boolean", "null" ] }, "trackClicks": { "type": [ "boolean", "null" ] }, "utm": { "type": [ "object", "null" ] }, "abTest": { "type": [ "object", "null" ] }, "push": { "type": [ "object", "null" ], "description": "options.push of a push campaign (title, text, URL, ttlMinutes)." }, "experimentConfig": { "type": [ "object", "null" ] }, "schedule": { "type": [ "object", "null" ], "description": "Frozen recipient-local schedule." }, "pushSchedule": { "type": [ "object", "null" ], "description": "Frozen at scheduling: sendAt, expiresAt, ttlMinutes and pace." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Push: the frozen expiry (sendAt + ttlMinutes)." }, "sendAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdBy": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ], "description": "The creator (read only)." }, "counts": { "additionalProperties": { "type": "integer" }, "type": [ "object", "null" ], "description": "Real recipients per status." }, "totalRecipients": { "type": [ "integer", "null" ] }, "audienceFingerprint": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ], "description": "Why the delivery worker paused the campaign." }, "system": { "type": [ "string", "null" ], "description": "automation or optin: managed by its journey or form." }, "experiment": { "type": [ "object", "null" ], "description": "State of the A/B test: status, mode, decision pending, affected, end of the hold." }, "automation": { "type": [ "object", "null" ] }, "usedByAutomations": { "items": { "type": "object" }, "type": [ "array", "null" ] }, "deliveryReview": { "properties": { "taskId": { "type": [ "string", "null" ] }, "taskStatus": { "type": [ "string", "null" ] }, "uncertain": { "type": "integer" }, "failed": { "type": "integer" } }, "type": "object", "description": "Real recipients whose delivery is uncertain or failed and their task marketing.delivery_review:." }, "experimentDecision": { "properties": { "taskId": { "type": [ "string", "null" ] }, "taskStatus": { "type": [ "string", "null" ] }, "pending": { "type": "boolean", "description": "Whether that task is open (a statistical plan waits for an administrator only after an inconclusive evaluation)." } }, "type": [ "object", "null" ], "description": "Only with marketing.experiments: the task marketing.experiment_decision:." }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of PATCH and actions." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "preview, schedule, pause, resume, cancel, clone, review_recipient and decide with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "channel", "status", "etag", "actions" ], "title": "ApiCampaign", "description": "An email, SMS or push campaign (its task is marketing.campaign:). The ETag is synthetic (W/\"h:…\") and serves as If-Match of every action of the campaign. Never its recipients." }, "ApiCampaignAnalytics": { "properties": { "campaignId": { "type": "string" }, "channel": { "type": "string", "enum": [ "email", "sms", "push" ] }, "recipients": { "type": "integer" }, "accepted": { "type": "integer" }, "sent": { "type": "integer" }, "delivered": { "type": "integer" }, "failed": { "type": "integer" }, "suppressed": { "type": "integer" }, "cancelled": { "type": "integer" }, "uniqueOpens": { "type": "integer" }, "uniqueClicks": { "type": "integer" }, "totalOpens": { "type": "integer" }, "totalClicks": { "type": "integer" }, "bounced": { "type": "integer" }, "unsubscribed": { "type": "integer" }, "complaints": { "type": "integer" }, "links": { "items": { "properties": { "url": { "type": "string" }, "totalClicks": { "type": "integer" }, "uniqueClicks": { "type": "integer" } }, "type": "object" }, "type": "array" }, "variations": { "items": { "type": "object" }, "type": "array" }, "roles": { "items": { "type": "object" }, "type": "array" }, "experiment": { "type": [ "object", "null" ], "description": "The A/B report: mode, hold, maturity and the decision." }, "push": { "type": [ "object", "null" ], "description": "Push: subscriptions reached, acceptance and optional clicks." }, "classification": { "type": [ "object", "null" ] } }, "type": "object", "required": [ "campaignId", "channel" ], "title": "ApiCampaignAnalytics", "description": "Aggregated metrics of the real recipients (marketing analytics of the app); never recipients." }, "ApiCampaignPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiCampaign" }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" }, "deliveryEnabled": { "type": "boolean", "description": "Whether the platform sends campaigns now (global switch)." } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiCampaignPage" }, "ApiCampaignRecipientPage": { "properties": { "campaignId": { "type": "string" }, "channel": { "type": "string", "enum": [ "email", "sms", "push" ] }, "reviewTaskId": { "type": [ "string", "null" ], "description": "marketing.delivery_review: when it is a task." }, "items": { "items": { "properties": { "id": { "type": "string", "description": "recipientId of review_recipient and of POST /api/v1/campaign-recipients/{id}/actions/review." }, "status": { "type": "string", "enum": [ "queued", "sending", "accepted", "delivered", "failed", "uncertain", "suppressed", "cancelled" ] }, "reviewable": { "type": "boolean", "description": "uncertain or failed: it can be reviewed." }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "variant": { "type": "string" }, "experimentRole": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "error": { "type": [ "string", "null" ], "description": "Reason of the last failure; any email or phone in it is masked unless the source reads it and reaches the contact (contactScope)." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "plannedAt": { "type": [ "string", "null" ], "format": "date-time" }, "localTimezone": { "type": [ "string", "null" ] }, "notBefore": { "type": [ "string", "null" ], "format": "date-time" }, "targetKind": { "type": "string" }, "subscriptionId": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Push: the frozen expiry of the message." }, "address": { "type": "string", "description": "Only when the source reads emails (email) or phones (SMS) and reaches the contact (contactScope)." } }, "type": "object" }, "type": "array", "description": "Real recipients in creation order; never a subject or a body." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "campaignId", "items", "nextCursor", "hasMore" ], "title": "ApiCampaignRecipientPage" }, "ApiChannel": { "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "whatsapp", "email", "social", "voice", "web", "web_form" ] }, "provider": { "type": "string", "enum": [ "whatsapp", "waha", "gmail", "microsoft", "imap", "messenger", "instagram", "twilio", "widget", "web_form" ] }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "status": { "type": "string" }, "archived": { "type": "boolean" }, "providerAvailable": { "type": "boolean" }, "authorizationValid": { "type": "boolean" }, "healthIssue": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "address": { "type": "string", "description": "Mailbox address of an email channel." }, "number": { "type": "string", "description": "Phone number of a voice or WhatsApp QR channel." }, "taskId": { "type": [ "string", "null" ], "description": "Its task while it is one." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks this record generates." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", null ] }, "signals": { "items": { "type": "string", "enum": [ "error", "reconnect_required", "verification_lost" ] }, "type": "array" }, "etag": { "type": [ "string", "null" ], "description": "W/\"h:<16 hex>\": the If-Match of verify." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." }, "setup": { "properties": { "verified": { "type": "boolean" }, "lastReceivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSentAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastFailedAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryObserved": { "type": "boolean" }, "voiceWebhooksConfigured": { "type": "boolean" }, "voiceMode": { "type": [ "string", "null" ] }, "assistantEnabled": { "type": "boolean" }, "recipientsConfigured": { "type": "boolean" }, "bookingsEnabled": { "type": "boolean" }, "calendarsConfigured": { "type": "boolean" } }, "type": "object", "description": "GET /api/v1/channels/{channel_id} only: activity and setup." } }, "type": "object", "required": [ "id", "type", "provider", "name", "enabled", "status", "taskIds", "actions" ], "title": "ApiChannel", "description": "A channel account. Never its configuration, credentials, tokens, webhook path or the agents' phones. While it needs attention its task is channel.health:account:." }, "ApiChannelPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiChannel" }, "type": "array", "description": "Oldest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiChannelPage" }, "ApiCompany": { "properties": { "id": { "type": "string", "description": "Customer company ID (after a merge, the kept one)." }, "name": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "address": { "type": "string" }, "description": { "type": "string" }, "ownerId": { "type": [ "string", "null" ] }, "ownerName": { "type": [ "string", "null" ] }, "archived": { "type": "boolean" }, "contactCount": { "type": "integer" }, "revision": { "type": "integer", "description": "The ETag is W/\"\"." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this company." }, "mergedRecordIds": { "items": { "type": "string" }, "type": "array", "description": "Companies merged into this one." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "Live tasks this company generates." }, "dealCount": { "type": "integer", "description": "Detail only." }, "conversationCount": { "type": "integer", "description": "Detail only." }, "activityCount": { "type": "integer", "description": "Detail only." } }, "type": "object", "required": [ "id", "name", "revision", "archived", "mergedFrom", "mergedRecordIds", "taskIds" ], "title": "ApiCompany" }, "ApiCompanyContactLink": { "properties": { "companyId": { "type": "string" }, "contactId": { "type": "string" }, "role": { "type": "string" }, "linked": { "type": "boolean" }, "replayed": { "type": "boolean" } }, "type": "object", "title": "ApiCompanyContactLink" }, "ApiCompanyContacts": { "properties": { "companyId": { "type": "string" }, "mergedFrom": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "items": { "type": "string" }, "type": "array", "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." }, "relationshipRole": { "type": "string" }, "reachable": { "type": "boolean", "description": "false: the source does not reach this contact and sees only its ID." } }, "type": "object", "required": [ "id", "relationshipRole", "reachable" ] }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and query); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "companyId", "items", "nextCursor", "hasMore" ], "title": "ApiCompanyContacts" }, "ApiCompanyHistory": { "properties": { "companyId": { "type": "string" }, "mergedFrom": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "type": { "type": "string", "description": "created, updated, contact_linked, contact_role, contact_unlinked, note…" }, "actor": { "properties": { "kind": { "type": "string", "enum": [ "user", "api", "system" ] }, "name": { "type": "string" } }, "type": "object" }, "changedFields": { "items": { "type": "string" }, "type": "array" }, "contactId": { "type": "string" }, "companyId": { "type": "string" }, "fromMerged": { "type": "boolean", "description": "The entry belongs to a company merged into this one." } }, "type": "object" }, "type": "array", "description": "Newest first; never note bodies or names of contacts." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and query); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "companyId", "items", "nextCursor", "hasMore" ], "title": "ApiCompanyHistory" }, "ApiCompanyNoteAnswer": { "properties": { "companyId": { "type": "string" }, "saved": { "type": "boolean" }, "replayed": { "type": "boolean" } }, "type": "object", "title": "ApiCompanyNoteAnswer" }, "ApiCompanyPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiCompany" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and query); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiCompanyPage" }, "ApiContactNoteAnswer": { "properties": { "contactId": { "type": "string" }, "replayed": { "type": "boolean" }, "note": { "properties": { "id": { "type": "string" }, "author": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" } }, "type": "object", "title": "ApiContactNoteAnswer" }, "ApiContactNotes": { "properties": { "contactId": { "type": "string" }, "mergedFrom": { "type": [ "string", "null" ] }, "items": { "items": { "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "author": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "contactId", "items" ], "title": "ApiContactNotes" }, "ApiContactPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string", "description": "Canonical RouterClip contact ID (after a merge, the kept record)." }, "revision": { "type": "integer", "description": "Revision of the contact; the ETag is W/\"\"." }, "result": { "type": "string", "enum": [ "created", "linked" ], "description": "Only in POST /contacts answers." }, "mergedFrom": { "type": [ "string", "null" ], "description": "The ID you asked for when it was merged into this contact." }, "mergedRecordIds": { "items": { "type": "string" }, "type": "array", "description": "IDs of records merged into this contact." }, "externalId": { "type": [ "string", "null" ], "description": "The externalId of your source linked to this contact." }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "language": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "timezone": { "type": [ "string", "null" ] }, "timezoneSource": { "type": [ "string", "null" ], "enum": [ "contact", "import", "api", "company", null ] }, "profilingOptOut": { "type": "boolean" }, "customValues": { "type": "object", "description": "The custom fields allowed in the source." } }, "type": "object", "required": [ "id", "revision", "mergedFrom", "mergedRecordIds", "externalId", "createdAt" ], "description": "Fields are present only with contacts:read and when they are in the source's read fields; notes, conversations, deals and consents are never exposed." }, "type": "array", "description": "Contacts the source reaches, by creation date, with the source's read fields." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and query); null on the last page." }, "hasMore": { "type": "boolean" }, "searchedFields": { "items": { "type": "string", "enum": [ "name", "email", "phone" ] }, "type": "array", "description": "Search only: name always; email and phone when the source may read them." } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiContactPage" }, "ApiContactScore": { "properties": { "contactId": { "type": "string", "description": "The kept record when the ID was absorbed by a merge (mergedFrom)." }, "mergedFrom": { "type": "string" }, "score": { "type": "integer" }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "points": { "type": "integer" }, "reason": { "type": "string" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Score entries, newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "contactId", "score", "items", "nextCursor", "hasMore" ], "title": "ApiContactScore" }, "ApiContactTasks": { "properties": { "contactId": { "type": "string", "description": "The contact (the kept record after a merge)." }, "mergedFrom": { "type": [ "string", "null" ] }, "items": { "items": { "$ref": "#/components/schemas/ApiTask" }, "type": "array", "description": "Live tasks of the kinds this key can read (the same page as GET /api/v1/tasks?contactId=)." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and query); null on the last page." }, "hasMore": { "type": "boolean" }, "indexedThrough": { "type": "string", "format": "date-time", "description": "Changes before this moment are in the index." } }, "type": "object", "required": [ "contactId", "items", "hasMore", "indexedThrough" ], "title": "ApiContactTasks" }, "ApiConversation": { "properties": { "id": { "type": "string" }, "purpose": { "type": "string", "enum": [ "support", "sales" ] }, "channel": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "resolved" ] }, "priority": { "type": "string" }, "assigneeId": { "type": [ "string", "null" ] }, "assigneeName": { "type": [ "string", "null" ] }, "aiEnabled": { "type": "boolean" }, "unreadCount": { "type": "integer" }, "snoozedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "ticketId": { "type": [ "string", "null" ] }, "taskIds": { "items": { "type": "string" }, "type": "array" }, "replyWindowClosed": { "type": "boolean", "description": "Detail of a WhatsApp, Instagram or Messenger conversation only (24-hour customer service window)." }, "replyWindowExpiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "type": "string", "description": "Only with support:content." }, "preview": { "type": "string", "description": "Last message; only with support:content." } }, "type": "object", "required": [ "id", "purpose", "channel", "status", "taskIds" ], "title": "ApiConversation", "description": "A conversation: never its thread identifiers or recipient address. Its ticket is one task (support.ticket)." }, "ApiConversationBulkAnswer": { "properties": { "runId": { "type": "string" }, "action": { "type": "string", "enum": [ "bulk" ] }, "dryRun": { "type": "boolean" }, "outcome": { "type": "string", "enum": [ "succeeded" ] }, "replayed": { "type": "boolean" }, "valid": { "type": "boolean", "description": "dryRun only." }, "result": { "properties": { "bulkRunId": { "type": "string" }, "count": { "type": "integer" }, "alreadyApplied": { "type": "boolean" }, "conversationIds": { "items": { "type": "string" }, "type": "array" } }, "type": "object", "description": "Execution: bulkRunId, count of changed conversations, alreadyApplied and conversationIds." }, "preview": { "properties": { "count": { "type": "integer" }, "changedCount": { "type": "integer" }, "macroName": { "type": "string" }, "changes": { "items": { "properties": { "conversationId": { "type": "string" }, "changed": { "type": "boolean" }, "before": { "properties": { "status": { "type": "string" }, "priority": { "type": "string" }, "assigneeId": { "type": [ "string", "null" ] }, "labelIds": { "items": { "type": "string" }, "type": "array" }, "aiEnabled": { "type": "boolean" } }, "type": "object" }, "after": { "properties": { "status": { "type": "string" }, "priority": { "type": "string" }, "assigneeId": { "type": [ "string", "null" ] }, "labelIds": { "items": { "type": "string" }, "type": "array" }, "aiEnabled": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object", "description": "dryRun: what would change (statuses, priorities, assignee and label IDs)." }, "confirm": { "properties": { "previewToken": { "type": "string" } }, "type": "object", "description": "dryRun: the token the execution needs." } }, "type": "object", "title": "ApiConversationBulkAnswer" }, "ApiConversationLabels": { "properties": { "conversationId": { "type": "string" }, "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "conversationId", "items" ], "title": "ApiConversationLabels" }, "ApiConversationMessages": { "properties": { "conversationId": { "type": "string" }, "items": { "items": { "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "senderType": { "type": "string" }, "status": { "type": "string" }, "body": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Oldest first; attachments are never served." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "conversationId", "items", "nextCursor", "hasMore" ], "title": "ApiConversationMessages" }, "ApiConversationNotes": { "properties": { "conversationId": { "type": "string" }, "items": { "items": { "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "kind": { "type": "string" }, "author": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "body": { "type": "string" }, "mentions": { "items": { "type": "object" }, "type": "array" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Internal notes, newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "conversationId", "items", "nextCursor", "hasMore" ], "title": "ApiConversationNotes" }, "ApiConversationPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiConversation" }, "type": "array", "description": "Latest activity first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" }, "searchedFields": { "items": { "type": "string", "enum": [ "subject", "body", "contactName", "contactEmail", "contactPhone" ] }, "type": "array", "description": "search only: subject and body and, of the contacts the source reaches (contactScope), the fields it may read (contactName, contactEmail, contactPhone)." } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiConversationPage" }, "ApiConversationSnooze": { "properties": { "conversationId": { "type": "string" }, "until": { "type": [ "string", "null" ], "format": "date-time", "description": "When the conversation wakes up; null when not snoozed." } }, "type": "object", "required": [ "conversationId", "until" ], "title": "ApiConversationSnooze" }, "ApiConversion": { "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "conversion", "order", "deal_won" ] }, "status": { "type": "string", "enum": [ "reported", "paid_declared", "partially_refunded", "refunded", "review", "unreconciled", "reconciled" ] }, "reviewReasons": { "items": { "type": "string" }, "type": "array" }, "namespace": { "properties": { "kind": { "type": "string" }, "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": "object" }, "conversionKey": { "type": "string" }, "conversionType": { "type": [ "string", "null" ] }, "orderId": { "type": [ "string", "null" ] }, "conversionId": { "type": [ "string", "null" ] }, "opportunityId": { "type": [ "string", "null" ] }, "closeCycle": { "type": [ "integer", "null" ] }, "opportunity": { "type": [ "object", "null" ] }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "The contact as this source may see it: its read fields, or only its ID when the source only reaches the contacts linked to it." }, "browserObserved": { "type": "boolean" }, "contactForgotten": { "type": "boolean" }, "money": { "properties": { "amount": { "properties": { "amount": { "type": "string" }, "amountMinor": { "type": "integer" }, "exponent": { "type": "integer" }, "currency": { "type": "string" } }, "type": [ "object", "null" ], "description": "Declared amount (never converted); null without amount." }, "refunded": { "properties": { "amount": { "type": "string" }, "amountMinor": { "type": "integer" }, "exponent": { "type": "integer" }, "currency": { "type": "string" } }, "type": [ "object", "null" ], "description": "Declared amount (never converted); null without amount." }, "net": { "properties": { "amount": { "type": "string" }, "amountMinor": { "type": "integer" }, "exponent": { "type": "integer" }, "currency": { "type": "string" } }, "type": [ "object", "null" ], "description": "Declared amount (never converted); null without amount." }, "verified": { "type": "null" } }, "type": "object", "description": "Declared figures only; verified payments do not exist in v1." }, "occurredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "attribution": { "type": "object" }, "verifiedPayments": { "type": "object", "description": "Only in the detail: verified payments are not available." }, "manualLinks": { "items": { "type": "object" }, "type": "array", "description": "Active manual links (V2-TRACE-04); a contact target shows its name only when this source may read it." }, "taskId": { "type": [ "string", "null" ] }, "taskIds": { "items": { "type": "string" }, "type": "array" }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "open", "done", null ] }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\" of the conversion." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions of its task (none in v1)." }, "observations": { "items": { "type": "object" }, "type": "array", "description": "Only in the detail: every fact that declared it." }, "candidates": { "items": { "type": "object" }, "type": "array", "description": "Only in the detail: touches and clicks of the window, with their quality." }, "qualityLabels": { "type": "object", "description": "Only in the detail." }, "links": { "items": { "type": "object" }, "type": "array", "description": "Only in the detail: every manual link, active and revoked." }, "linking": { "type": "object", "description": "Only in the detail: what the app's administrator can link." } }, "type": "object", "required": [ "id", "kind", "status", "taskIds", "etag", "actions" ], "title": "ApiConversion", "description": "A declared conversion, order or won deal with its attribution decision (TRACE-02). A conversion without a common key is the task marketing.conversion_reconciliation:. Never visitor hashes, envelopes or secrets; the contact as this source may see it." }, "ApiConversionPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiConversion" }, "type": "array", "description": "Newest first." }, "total": { "type": "integer" }, "counts": { "additionalProperties": { "type": "integer" }, "type": "object", "description": "Conversions per status." }, "statuses": { "items": { "type": "string" }, "type": "array" }, "policy": { "type": "object" }, "verifiedPayments": { "type": "object" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiConversionPage" }, "ApiCsatDelivery": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ], "description": "Only when the invitation is a task." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "open", "in_progress", "needs_review", "done", "cancelled", null ] }, "signals": { "items": { "type": "string", "enum": [ "uncertain", "failed" ] }, "type": "array" }, "conversationId": { "type": "string" }, "ticketId": { "type": [ "string", "null" ] }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "closeCycle": { "type": "integer" }, "status": { "type": "string", "enum": [ "scheduled", "manual_prepared", "suppressed", "paused_identity", "queued", "sending", "accepted", "retry_wait", "failed", "uncertain", "cancelled", "expired" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "automatic", "manual" ] }, "channel": { "type": "string" }, "mailboxId": { "type": [ "string", "null" ], "description": "The mailbox of the conversation that sends it." }, "language": { "type": "string" }, "notBefore": { "type": [ "string", "null" ], "format": "date-time" }, "eligibleUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "After it the invitation can no longer be sent (72 h after the close)." }, "invitedAt": { "type": [ "string", "null" ], "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "attempts": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer" }, "etag": { "type": "string", "description": "W/\"\": the If-Match of actions (expectedRevision)." }, "cycle": { "properties": { "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reopenedAt": { "type": [ "string", "null" ], "format": "date-time" }, "closeReason": { "type": "string" } }, "type": [ "object", "null" ] }, "survey": { "properties": { "id": { "type": "string" }, "state": { "type": "string", "enum": [ "answered", "revoked", "expired", "active" ] }, "rating": { "type": [ "integer", "null" ] }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "string" } }, "type": [ "object", "null" ], "description": "State of the survey link (never the link)." }, "lastAttempt": { "properties": { "number": { "type": "integer" }, "status": { "type": "string" }, "phase": { "type": [ "string", "null" ] }, "failureCode": { "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": [ "object", "null" ] }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions of the task kind with their availability for this key and delegated user." }, "recipient": { "type": [ "string", "null" ], "description": "Masked address; only when the source may read emails and reaches the contact (contactScope)." }, "attemptHistory": { "items": { "properties": { "number": { "type": "integer" }, "status": { "type": "string" }, "phase": { "type": [ "string", "null" ] }, "failureCode": { "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": [ "object", "null" ] }, "type": "array", "description": "GET /api/v1/csat/deliveries/{id} only: every attempt (codes and dates)." }, "history": { "items": { "properties": { "action": { "type": "string", "enum": [ "send_now", "cancel", "revoke_link", "retry", "review" ] }, "decision": { "type": [ "string", "null" ] }, "fromStatus": { "type": "string" }, "toStatus": { "type": "string" }, "verificationSource": { "type": [ "string", "null" ] }, "actor": { "properties": { "kind": { "type": "string", "enum": [ "user", "service" ] }, "id": { "type": "string" } }, "type": "object" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "reason": { "type": "string", "description": "Only with support:content." }, "evidence": { "type": "string", "description": "Only with support:content." } }, "type": "object" }, "type": "array", "description": "GET /api/v1/csat/deliveries/{id} only: every team action." } }, "type": "object", "required": [ "id", "conversationId", "closeCycle", "status", "revision", "etag", "actions" ], "title": "ApiCsatDelivery", "description": "The CSAT invitation of one close cycle (its task, while it needs attention, is support.csat_delivery:). Never a survey link, token, hash or Message-ID." }, "ApiCsatDeliveryPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiCsatDelivery" }, "type": "array", "description": "Newest first." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" }, "sending": { "properties": { "available": { "type": "boolean" }, "blockers": { "items": { "type": "string", "enum": [ "sending_switch_off", "feature_disabled", "policy_disabled", "public_origin_missing" ] }, "type": "array" } }, "type": "object", "description": "Whether invitations can be sent now and why not." } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore", "sending" ], "title": "ApiCsatDeliveryPage" }, "ApiCsatSurveys": { "properties": { "conversationId": { "type": "string" }, "ticketId": { "type": [ "string", "null" ] }, "currentCycle": { "type": "integer" }, "current": { "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "rating": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "language": { "type": "string" }, "closeCycle": { "type": "integer" }, "source": { "type": "string", "enum": [ "automatic", "manual", "legacy" ] }, "state": { "type": "string", "enum": [ "answered", "revoked", "expired", "active" ] }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "feedback": { "type": "string", "description": "The customer's comment; only with support:content." }, "historical": { "type": "boolean" }, "invitation": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "scheduled", "manual_prepared", "suppressed", "paused_identity", "queued", "sending", "accepted", "retry_wait", "failed", "uncertain", "cancelled", "expired" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "attempts": { "type": "integer" }, "invitedAt": { "type": [ "string", "null" ], "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer" } }, "type": [ "object", "null" ], "description": "The automatic invitation of the cycle (only with support.csat_auto)." } }, "type": [ "object", "null" ], "description": "The survey of the current close cycle or, without one, the most recent (historical)." }, "items": { "items": { "properties": { "closeCycle": { "type": "integer" }, "cycle": { "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "caseId": { "type": [ "string", "null" ] }, "closeCycle": { "type": "integer" }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reopenedAt": { "type": [ "string", "null" ], "format": "date-time" }, "closedById": { "type": [ "string", "null" ] }, "closeReason": { "type": "string" }, "lastHumanReplyAt": { "type": [ "string", "null" ], "format": "date-time" }, "recipientSource": { "type": [ "string", "null" ] }, "channel": { "type": "string" }, "assigneeId": { "type": [ "string", "null" ] }, "teamId": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "survey": { "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "rating": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "language": { "type": "string" }, "closeCycle": { "type": "integer" }, "source": { "type": "string", "enum": [ "automatic", "manual", "legacy" ] }, "state": { "type": "string", "enum": [ "answered", "revoked", "expired", "active" ] }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "feedback": { "type": "string", "description": "The customer's comment; only with support:content." } }, "type": [ "object", "null" ], "description": "Never the survey link, its token or hash." }, "invitation": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "scheduled", "manual_prepared", "suppressed", "paused_identity", "queued", "sending", "accepted", "retry_wait", "failed", "uncertain", "cancelled", "expired" ] }, "reason": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "attempts": { "type": "integer" }, "invitedAt": { "type": [ "string", "null" ], "format": "date-time" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "revision": { "type": "integer" } }, "type": [ "object", "null" ], "description": "The automatic invitation of the cycle (only with support.csat_auto)." } }, "type": "object" }, "type": "array", "description": "Close cycles, newest first." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "conversationId", "currentCycle", "items", "nextCursor", "hasMore" ], "title": "ApiCsatSurveys" }, "ApiCustomerNote": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string", "description": "support.customer_message:." }, "status": { "type": "string", "enum": [ "pending", "done" ] }, "taskStatus": { "type": "string", "enum": [ "open", "needs_review", "done" ], "description": "needs_review while an alert of a pending message is unconfirmed." }, "signals": { "items": { "type": "string", "enum": [ "uncertain", "failed" ] }, "type": "array" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "conversationId": { "type": "string" }, "ticketId": { "type": [ "string", "null" ] }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "recipient": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" } }, "type": [ "object", "null" ], "description": "The directory contact responsible (ID, name and category only)." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "items": { "properties": { "id": { "type": "string", "description": "The jobId of review_notification." }, "medium": { "type": "string", "enum": [ "email", "phone", "whatsapp" ] }, "status": { "type": "string", "enum": [ "queued", "sending", "sent", "failed", "uncertain", "cancelled" ] }, "errorCode": { "type": "string", "description": "Stable reason of a failed or unconfirmed alert." }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Team alerts by channel (never the recipient's address or phone)." }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of PATCH and actions." }, "body": { "type": "string", "description": "The customer's text; only with support:content." } }, "type": "object", "required": [ "id", "taskId", "status", "taskStatus", "conversationId", "deliveries", "etag" ], "title": "ApiCustomerNote", "description": "A message a customer left for a person of the company directory, with its team alerts (its task is support.customer_message:). The directory itself is never exposed." }, "ApiCustomerNotePage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiCustomerNote" }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiCustomerNotePage" }, "ApiDeal": { "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "contactId": { "type": "string" }, "contactName": { "type": [ "string", "null" ], "description": "Only when the source may read the name and reaches the contact." }, "amount": { "type": [ "string", "null" ], "description": "Decimal string with the currency's decimals." }, "currency": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "won", "lost", "archived" ] }, "stage": { "type": "string", "enum": [ "lead", "qualified", "proposal", "negotiation", "won", "lost" ], "description": "Canonical stage." }, "pipelineId": { "type": "string" }, "pipelineName": { "type": "string" }, "stageId": { "type": "string" }, "stageName": { "type": "string" }, "stageCategory": { "type": "string", "enum": [ "open", "won", "lost" ] }, "probability": { "type": "integer", "description": "Effective probability (100 won, 0 lost)." }, "probabilityOverride": { "type": [ "integer", "null" ] }, "forecastCategory": { "type": "string", "enum": [ "pipeline", "best_case", "commit", "omitted" ] }, "ownerId": { "type": [ "string", "null" ] }, "ownerName": { "type": [ "string", "null" ] }, "expectedClose": { "type": [ "string", "null" ], "format": "date", "description": "YYYY-MM-DD." }, "lostReason": { "type": "string" }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "closeCycle": { "type": "integer" }, "source": { "type": "string" }, "customValues": { "additionalProperties": true, "type": "object" }, "archived": { "type": "boolean" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "stageEnteredAt": { "type": [ "string", "null" ], "format": "date-time" }, "stageAgeDays": { "type": [ "integer", "null" ] }, "lastInteractionAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextActivity": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "title": { "type": "string" }, "activityKind": { "type": "string" }, "priority": { "type": "string" }, "dueAt": { "type": "string", "format": "date-time" }, "assigneeId": { "type": [ "string", "null" ] }, "assigneeName": { "type": [ "string", "null" ] }, "originType": { "type": [ "string", "null" ] }, "overdue": { "type": "boolean" } }, "type": [ "object", "null" ], "description": "The first open follow-up by due date." }, "openActivityCount": { "type": "integer" }, "overdueActivityCount": { "type": "integer" }, "warnings": { "items": { "properties": { "code": { "type": "string", "enum": [ "missing_fields", "stale_stage", "idle", "no_next_action", "activity_overdue", "close_overdue" ] }, "fields": { "items": { "type": "string" }, "type": "array", "description": "missing_fields: the important fields missing." }, "days": { "type": "integer" }, "threshold": { "type": "integer" }, "dueAt": { "type": "string", "format": "date-time" }, "expectedClose": { "type": "string", "format": "date" } }, "type": "object", "required": [ "code" ] }, "type": "array", "description": "Computed warnings of an open, active deal." }, "health": { "type": "string", "enum": [ "ok", "attention", "closed", "archived" ] }, "attention": { "properties": { "taskId": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "cancelled" ] }, "signals": { "items": { "type": "string", "enum": [ "overdue", "missing_fields", "stale_stage", "no_next_activity", "close_date_passed" ] }, "type": "array" } }, "type": [ "object", "null" ], "description": "The crm.deal_attention task while the deal is one." }, "revision": { "type": "integer", "description": "The ETag is W/\"\"." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks of the deal (its attention task)." } }, "type": "object", "required": [ "id", "title", "state", "stage", "amount", "currency", "warnings", "revision", "taskIds" ], "title": "ApiDeal", "description": "A deal as the board, the list and the deal card show it (PIPE-03). The ETag is W/\"\"." }, "ApiDealHistory": { "properties": { "dealId": { "type": "string" }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "type": { "type": "string", "enum": [ "created", "updated", "stage_changed", "archived", "restored", "result_corrected" ] }, "revision": { "type": [ "integer", "null" ] }, "actor": { "properties": { "kind": { "type": "string", "enum": [ "user", "api", "system" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "changedFields": { "items": { "type": "string" }, "type": "array", "description": "API names; custom: for custom values." } }, "type": "object" }, "type": "array", "description": "Newest first; never values or bodies." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "dealId", "items", "nextCursor", "hasMore" ], "title": "ApiDealHistory" }, "ApiDealPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiDeal" }, "type": "array", "description": "By creation date." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" }, "asOf": { "type": "string", "format": "date-time" }, "timezone": { "type": "string", "description": "Zone of the company: today, expected close and overdue use it." } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiDealPage" }, "ApiDuplicatePage": { "properties": { "entity": { "type": "string", "enum": [ "contact", "company" ] }, "status": { "type": "string", "enum": [ "pending", "dismissed" ] }, "recordId": { "type": [ "string", "null" ] }, "items": { "items": { "properties": { "id": { "type": "string", "description": ":: (idA < idB) for a pair; :group: for a group of more than six records sharing an identity (never a task)." }, "kind": { "type": "string", "enum": [ "pair", "group" ] }, "entity": { "type": "string", "enum": [ "contact", "company" ] }, "records": { "items": { "properties": { "id": { "type": "string" }, "reachable": { "type": "boolean", "description": "Contacts: false when the source does not reach it (only its ID)." }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "company": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "archived": { "type": "boolean" }, "revision": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "hiddenWhatsApp": { "type": "boolean" }, "identityReview": { "type": "boolean" } }, "type": "object", "required": [ "id" ], "description": "Contact fields only when the source may read them (contactReadFields) and reaches the contact." }, "type": "array" }, "total": { "type": "integer", "description": "Members of a group." }, "reasons": { "items": { "properties": { "code": { "type": "string" } }, "type": "object", "required": [ "code" ], "description": "same_email, same_phone, identity_review, same_website_host or same_normalized_name; key only when it is not personal or the source may read it." }, "type": "array" }, "contradictions": { "items": { "properties": { "code": { "type": "string" } }, "type": "object", "required": [ "code" ] }, "type": "array" }, "sharedIdentity": { "type": "boolean" }, "sharedContacts": { "type": "integer" }, "fingerprint": { "type": [ "string", "null" ], "description": "Send it with dismiss/restore: a change of identity is 409." }, "decision": { "type": [ "object", "null" ] }, "previouslyDismissed": { "type": "boolean" }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "Tasks of this resource (crm.duplicate_review / crm.merge_review)." } }, "type": "object", "required": [ "id", "kind", "entity", "records", "reasons", "taskIds" ] }, "type": "array" }, "total": { "type": "integer" }, "truncated": { "type": "boolean", "description": "The detection reached its scan limit: some candidates may be missing." }, "recordBlockers": { "items": { "type": "string" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ], "description": "Send it as cursor for the next page (same filters)." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "entity", "status", "items", "total", "nextCursor", "hasMore" ], "title": "ApiDuplicatePage" }, "ApiEventFeedPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string", "description": "RouterClip event ID (32 hex)." }, "type": { "type": "string", "enum": [ "contact.created", "contact.updated", "contact.subscription_confirmed", "contact.date_reached", "contact.merged", "contact.grade_changed", "custom", "deal.created", "deal.updated", "deal.stage_changed", "deal.won", "deal.lost", "deal.reopened", "deal.archived", "deal.restored", "deal.stale", "deal.close_date_passed", "pipeline.configuration_changed", "activity.completed", "activity.overdue", "sequence.enrollment_started", "sequence.reply_detected", "sequence.enrollment_ended", "playbook.completed", "conversation.created", "conversation.assigned", "conversation.unassigned", "conversation.closed", "conversation.reopened", "conversation.unanswered", "customer.waiting", "waiting_customer.elapsed", "ticket.created", "ticket.status_changed", "ticket.portal_reply", "sla.warning", "sla.breached", "csat.responded", "calendar.booking_confirmed", "calendar.booking_cancelled", "email.link_clicked", "journey.enrolled", "journey.completed", "journey.goal_reached", "web.form_submitted", "web.campaign_arrival", "conversion.reported", "order.paid", "order.refunded" ] }, "schemaVersion": { "type": "integer", "enum": [ 1 ] }, "occurredAt": { "type": "string", "format": "date-time" }, "subject": { "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ], "required": [ "type", "id" ], "description": "The contact of the fact ({type: contact, id}; a merged contact answers the kept one), else the record it is about; null when there is neither (a contact fact after the contact was deleted)." }, "aggregate": { "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ], "required": [ "type", "id" ], "description": "The record the fact is about (opportunity, conversation, ticket, activity…); read it with readWith of GET /api/v1/event-types, or see aggregatesWithoutDetail there for the ones without a detail route." }, "version": { "type": [ "integer", "null" ], "description": "Revision of the aggregate when it has one: discard a fact whose version is not newer than the one you know." }, "changedFields": { "items": { "type": "string" }, "type": "array", "description": "Names of the fields that changed, when the fact has them (never values)." } }, "type": "object", "required": [ "id", "type", "schemaVersion", "occurredAt", "subject", "aggregate", "version" ], "description": "The «despertador» payload (also the body of the company webhooks): IDs, type and version only." }, "type": "array" }, "nextCursor": { "type": "string", "description": "Send it as after in the next request (same types); it never expires." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiEventFeedPage" }, "ApiEventTypes": { "properties": { "schemaVersion": { "type": "integer" }, "payloadFields": { "items": { "type": "string" }, "type": "array" }, "types": { "items": { "properties": { "type": { "type": "string" }, "label": { "properties": { "es": { "type": "string" }, "en": { "type": "string" } }, "type": "object" }, "area": { "type": "string" }, "areaName": { "properties": { "es": { "type": "string" }, "en": { "type": "string" } }, "type": "object" }, "scope": { "type": "string" }, "feature": { "type": [ "string", "null" ] }, "featureEnabled": { "type": "boolean" }, "available": { "type": "boolean", "description": "This key can read it now (area scope and feature on)." }, "recordedWhenWanted": { "type": "boolean", "description": "ARQ-34 fact: recorded only while a flow, a webhook or a key that reads it wants it." } }, "type": "object" }, "type": "array" }, "excluded": { "items": { "properties": { "prefix": { "type": "string" }, "reason": { "type": "string" }, "useInstead": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array" }, "readWith": { "additionalProperties": { "type": "string" }, "type": "object", "description": "Aggregate type → the /api/v1 resource that reads it ({id} is aggregate.id). The other aggregates of the feed are in aggregatesWithoutDetail." }, "aggregatesWithoutDetail": { "items": { "properties": { "aggregateType": { "type": "string" }, "reason": { "type": "string", "enum": [ "listOnly", "externalReference", "noResource" ] }, "listPath": { "type": [ "string", "null" ] } }, "type": "object", "required": [ "aggregateType", "reason", "listPath" ] }, "type": "array", "description": "Aggregates of the feed without a detail route by aggregate.id: listOnly (find aggregate.id in the items of listPath), externalReference (aggregate.id is your own conversionId or orderId sent in the event; the attributed conversion is in listPath) or noResource (no /api/v1 resource reads it: read the subject)." }, "scope": { "type": "string" }, "feature": { "type": "string" } }, "type": "object", "required": [ "schemaVersion", "types", "readWith", "aggregatesWithoutDetail" ], "title": "ApiEventTypes" }, "ApiFormPlacement": { "properties": { "id": { "type": "string" }, "publicId": { "type": "string", "description": "Public and not secret: the inline marker and ?pl=." }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "popup", "inline" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "revision": { "type": "integer" }, "rules": { "type": "object", "description": "Trigger, paths, device, dates, frequency and zIndex." }, "site": { "type": [ "object", "null" ] }, "form": { "type": [ "object", "null" ] }, "live": { "type": "boolean", "description": "Served now on the website." }, "blockers": { "items": { "type": "string" }, "type": "array", "description": "Why it is not (or could not be) served now." }, "submissions": { "type": "integer" }, "createdBy": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "updatedBy": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "activatedBy": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "taskId": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "open", "waiting", "done", "cancelled" ] }, "etag": { "type": "string", "description": "W/\"\": the If-Match of the actions." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "publicId", "name", "kind", "status", "revision", "taskId", "taskStatus", "etag", "actions" ], "title": "ApiFormPlacement", "description": "A popup or inline placement of a hosted form on a verified website (its task is marketing.placement:). The ETag is W/\"\". Never the install snippet." }, "ApiFormPlacementPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiFormPlacement" }, "type": "array", "description": "Archived ones last, newest first." }, "total": { "type": "integer" }, "limits": { "type": "object", "description": "Limits per website and of the rules." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiFormPlacementPage" }, "ApiJourney": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ], "description": "marketing.journey_attention: while it is (or was) a task." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", "cancelled", null ] }, "signals": { "items": { "type": "string", "enum": [ "failed", "error" ] }, "type": "array" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "cancelled" ] }, "trigger": { "type": "string", "enum": [ "manual", "segment", "event", "date", "api" ] }, "triggerConfig": { "type": [ "object", "null" ] }, "entryPolicy": { "type": [ "object", "null" ] }, "eventsEnabled": { "type": [ "boolean", "null" ] }, "activatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "filters": { "type": [ "object", "null" ] }, "steps": { "items": { "type": "object" }, "type": [ "array", "null" ] }, "counts": { "additionalProperties": { "type": "integer" }, "type": [ "object", "null" ], "description": "Enrollments per status." }, "skippedSends": { "additionalProperties": { "type": "integer" }, "type": [ "object", "null" ] }, "pausedSends": { "additionalProperties": { "type": "integer" }, "type": [ "object", "null" ], "description": "Sends the delivery worker paused, per reason." }, "unconfirmedSends": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "versioning": { "type": [ "string", "null" ] }, "currentVersionId": { "type": [ "string", "null" ] }, "currentVersion": { "type": [ "integer", "null" ] }, "draftRevision": { "type": [ "integer", "null" ] }, "hasDraft": { "type": [ "boolean", "null" ] }, "allowedForSource": { "type": "boolean", "description": "In the source's allowed list (allowedAutomationIds)." }, "enrollable": { "type": "boolean", "description": "Allowed for the source, active and with the API trigger: POST …/enroll (automations:enroll) can enroll into it." }, "attention": { "properties": { "failedEnrollments": { "type": "integer" }, "pausedEnrollments": { "type": "integer" }, "pausedSends": { "type": "integer" }, "retriableSends": { "type": "integer" } }, "type": "object" }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of the actions." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "status", "trigger", "enrollable", "etag", "actions" ], "title": "ApiJourney", "description": "A journey of the company (its attention task is marketing.journey_attention:). The ETag is synthetic (W/\"h:…\") and serves as If-Match of every action of the journey." }, "ApiJourneyEnrollmentPage": { "properties": { "automationId": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string", "description": "enrollmentId of resume_enrollment/cancel_enrollment and of POST /api/v1/journey-enrollments/{id}/actions/{action}." }, "automationId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "waiting", "paused", "completed", "cancelled", "failed" ] }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "currentStepId": { "type": [ "string", "null" ] }, "nextRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ], "description": "Any email or phone in it is masked unless the source reads both." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "entryEventId": { "type": [ "string", "null" ] }, "entryEventType": { "type": [ "string", "null" ] }, "versionId": { "type": [ "string", "null" ] }, "version": { "type": [ "integer", "null" ] }, "wait": { "type": [ "object", "null" ] }, "skippedSteps": { "items": { "type": "object" }, "type": "array" }, "deliveryIssues": { "items": { "type": "object" }, "type": "array", "description": "Sends paused, failed or unconfirmed; never an address." }, "taskId": { "type": [ "string", "null" ] }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\" of the enrollment." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object" }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "automationId", "items", "nextCursor", "hasMore" ], "title": "ApiJourneyEnrollmentPage" }, "ApiJourneyVersions": { "properties": { "automationId": { "type": "string" }, "status": { "type": "string" }, "versioning": { "type": "string", "enum": [ "live_template", "versioned" ] }, "currentVersionId": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "published", "superseded", "retired" ] }, "current": { "type": "boolean" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedBy": { "type": [ "string", "null" ] }, "supersededAt": { "type": [ "string", "null" ], "format": "date-time" }, "retiredAt": { "type": [ "string", "null" ], "format": "date-time" }, "contentHash": { "type": "string" }, "trigger": { "type": "string" }, "stepIds": { "items": { "type": "string" }, "type": "array" }, "enrollments": { "type": "object" }, "sends": { "type": "object" }, "changes": { "type": "object", "description": "Definition and frozen content compared with the previous version." } }, "type": "object" }, "type": "array", "description": "Newest first (at most 100)." }, "unversionedEnrollments": { "type": "object" }, "unversionedSends": { "type": "object" }, "draft": { "properties": { "revision": { "type": "integer", "description": "The draftRevision publish_version needs." }, "hasDraft": { "type": "boolean" }, "editable": { "type": "boolean" }, "changes": { "type": [ "object", "null" ] }, "contentChanges": { "type": [ "object", "null" ] } }, "type": "object" }, "taskId": { "type": [ "string", "null" ] }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "open", "done", "cancelled", null ] }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\" of the journey: the If-Match of publish_version." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "automationId", "versioning", "items", "draft", "etag", "actions" ], "title": "ApiJourneyVersions", "description": "The versions of a journey with their differences, enrollments and sends, and the summary of its draft (its task is marketing.journey_version:). The ETag is the journey's (W/\"h:…\")." }, "ApiKnowledgeDocument": { "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string", "enum": [ "manual", "upload", "url", "google_drive" ] }, "status": { "type": "string", "enum": [ "indexed", "local", "index_pending" ] }, "language": { "type": "string", "enum": [ "es", "en" ] }, "agentTypes": { "items": { "type": "string" }, "type": "array" }, "chunkCount": { "type": "integer" }, "storageBytes": { "type": "integer" }, "contentHash": { "type": [ "string", "null" ] }, "filename": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ], "description": "The link of an imported document without query or fragment." }, "googleDrive": { "type": "boolean", "description": "Imported with an authorized Google Drive connection." }, "refreshIntervalHours": { "type": [ "integer", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastChangedAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextRefreshAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "taskId": { "type": [ "string", "null" ], "description": "Its task while it is one." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks this record generates." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", null ] }, "signals": { "items": { "type": "string", "enum": [ "error", "failed" ] }, "type": "array" }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of PATCH and refresh." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." }, "content": { "type": "string", "description": "GET /api/v1/knowledge/documents/{document_id}?include=content only." } }, "type": "object", "required": [ "id", "title", "kind", "status", "taskIds", "etag", "actions" ], "title": "ApiKnowledgeDocument", "description": "A knowledge document. While its source fails or its indexing is late its task is knowledge.source_error:. Never the Google connection or the stored original." }, "ApiKnowledgeDocumentPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiKnowledgeDocument" }, "type": "array", "description": "Newest first; never the text." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiKnowledgeDocumentPage" }, "ApiKnowledgeStorage": { "properties": { "usedBytes": { "type": "integer" }, "limitBytes": { "type": "integer" }, "remainingBytes": { "type": "integer" }, "uploadMaxBytes": { "type": "integer" }, "documentCount": { "type": "integer" }, "requestedLimitBytes": { "type": [ "integer", "null" ] }, "requestedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object", "required": [ "usedBytes", "limitBytes", "remainingBytes" ], "title": "ApiKnowledgeStorage", "description": "The knowledge storage of the company." }, "ApiMailDomainDns": { "properties": { "domainId": { "type": "string" }, "records": { "items": { "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" }, "note": { "type": "string" }, "redacted": { "type": "boolean", "description": "The value carries a verification token." } }, "type": "object" }, "type": "array" }, "checks": { "additionalProperties": { "type": "boolean" }, "type": "object" }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dnsReady": { "type": "boolean" }, "operatorRequirements": { "items": { "type": "string" }, "type": "array" } }, "type": "object", "required": [ "domainId", "records", "checks", "dnsReady" ], "title": "ApiMailDomainDns", "description": "The DNS records of a hosted mail domain; the value of the ownership TXT is redacted (see it in the app)." }, "ApiMailDomainPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "hostname": { "type": "string" }, "status": { "type": "string", "enum": [ "disabled", "pending_verification", "pending_apply", "applied" ] }, "dnsStatus": { "additionalProperties": { "type": "boolean" }, "type": "object" }, "enabled": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "appliedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dnsCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownershipLostAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownershipRevokeAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "taskId": { "type": [ "string", "null" ], "description": "Its task while it is one." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks this record generates." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", null ] }, "signals": { "items": { "type": "string", "enum": [ "error", "reconnect_required", "verification_lost" ] }, "type": "array" }, "etag": { "type": [ "string", "null" ], "description": "W/\"h:<16 hex>\": the If-Match of verify." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "status", "enabled", "taskIds", "actions" ], "description": "A hosted mail domain; never its verification token or DKIM key. While it needs attention its task is channel.health:mail_domain:." }, "type": "array", "description": "By name." }, "hostingEnabled": { "type": "boolean", "description": "Mail hosting is configured on this installation." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiMailDomainPage" }, "ApiMarketingConnectionPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": "string", "enum": [ "smtp", "twilio", "listmonk" ] }, "channel": { "type": "string", "enum": [ "email", "sms" ] }, "enabled": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verificationLost": { "type": "boolean", "description": "It was verified, but the platform origin or the SMS setup changed since." }, "limits": { "additionalProperties": { "type": "integer" }, "type": "object" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "sender": { "properties": { "email": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "type": "object", "description": "Email connections." }, "publicOriginChanged": { "type": "boolean" }, "taskId": { "type": [ "string", "null" ], "description": "Its task while it is one." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks this record generates." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", null ] }, "signals": { "items": { "type": "string", "enum": [ "error", "reconnect_required", "verification_lost" ] }, "type": "array" }, "etag": { "type": [ "string", "null" ], "description": "W/\"h:<16 hex>\": the If-Match of verify." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "provider", "channel", "enabled", "taskIds", "actions" ], "description": "An email or SMS marketing connection without credentials, hosts, user names or provider IDs. While it needs attention its task is channel.health:connection:." }, "type": "array", "description": "Oldest first." }, "deliveryEnabled": { "type": "boolean", "description": "MARKETING_SEND_ENABLED of the platform." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiMarketingConnectionPage" }, "ApiMarketingTemplate": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "content": { "type": [ "object", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object", "required": [ "id", "name" ], "title": "ApiMarketingTemplate", "description": "An email template of the company." }, "ApiMarketingTemplatePage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiMarketingTemplate" }, "type": "array", "description": "Most recently changed first." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiMarketingTemplatePage" }, "ApiMarketingWebhookDeliveryPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "webhookId": { "type": "string" }, "eventId": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "queued", "sending", "delivered", "failed" ] }, "attempts": { "type": "integer" }, "totalAttempts": { "type": "integer" }, "lastStatusCode": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "retryable": { "type": "boolean", "description": "Failed and its webhook enabled." } }, "type": "object" }, "type": "array", "description": "Newest first; never the body." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiMarketingWebhookDeliveryPage" }, "ApiMarketingWebhookPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "description": "https://host/… (masked)." }, "events": { "items": { "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "description": "receiver_gone: the receiver answered 410." }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "authorized": { "type": "boolean" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "properties": { "failed": { "type": "integer" }, "pending": { "type": "integer" } }, "type": "object" }, "taskId": { "type": [ "string", "null" ], "description": "Its task while it is one." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks this record generates." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "needs_review", "done", null ] }, "signals": { "items": { "type": "string", "enum": [ "failed", "error" ] }, "type": "array" }, "etag": { "type": [ "string", "null" ] }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "url", "events", "enabled", "deliveries", "taskIds", "actions" ], "description": "A marketing webhook. The URL is masked (host only) and the secret is never shown. While it has failed deliveries its task is integration.webhook_failed:marketing:." }, "type": "array" }, "deliveryEnabled": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiMarketingWebhookPage" }, "ApiMemberAvailability": { "properties": { "userId": { "type": "string" }, "availability": { "type": "string", "enum": [ "online", "away", "offline" ] }, "capacity": { "type": [ "integer", "null" ] }, "assigned": { "type": "integer", "description": "Waiting conversations the queue assigned after the change." }, "replayed": { "type": "boolean" } }, "type": "object", "required": [ "userId", "availability" ], "title": "ApiMemberAvailability" }, "ApiMentionPage": { "properties": { "userId": { "type": "string", "description": "The delegated user (the recipient)." }, "unreadCount": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ], "description": "support.mention: (support conversations)." }, "conversationId": { "type": "string" }, "purpose": { "type": "string", "enum": [ "support", "sales" ] }, "ticketId": { "type": [ "string", "null" ] }, "kind": { "type": "string", "description": "user, sla, portal or attention." }, "authorName": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "readAt": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "type": [ "string", "null" ], "description": "Only with support:content (support conversations)." }, "preview": { "type": "string", "description": "Start of the note; only with support:content (support conversations)." } }, "type": "object" }, "type": "array", "description": "Unread first, newest first." } }, "type": "object", "required": [ "userId", "unreadCount", "items" ], "title": "ApiMentionPage" }, "ApiMergeOperation": { "properties": { "id": { "type": [ "string", "null" ] }, "operationId": { "type": [ "string", "null" ] }, "entity": { "type": "string", "enum": [ "contact", "company" ] }, "sourceId": { "type": "string" }, "sourceName": { "type": [ "string", "null" ] }, "survivorId": { "type": "string" }, "survivorName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "completed", "undone" ] }, "mergedAt": { "type": [ "string", "null" ], "format": "date-time" }, "actorId": { "type": [ "string", "null" ] }, "actorName": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "reviewPending": { "type": "boolean" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedByName": { "type": [ "string", "null" ] }, "undoUntil": { "type": [ "string", "null" ], "format": "date-time" }, "undoneAt": { "type": [ "string", "null" ], "format": "date-time" }, "undoneByName": { "type": [ "string", "null" ] }, "undoAvailable": { "type": "boolean" }, "undoUnavailableReason": { "type": [ "string", "null" ] }, "counts": { "type": "object" }, "actions": { "items": { "properties": { "code": { "type": "string" }, "count": { "type": "integer" } }, "type": "object" }, "type": "array" }, "legacy": { "type": "boolean", "description": "Merged before the journal existed (no operation)." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "Tasks of this resource (crm.duplicate_review / crm.merge_review)." }, "mutations": { "items": { "properties": { "seq": { "type": "integer" }, "table": { "type": "string" }, "column": { "type": "string" }, "rowPk": { "type": "string" }, "originRecordId": { "type": "string" }, "action": { "type": "string" } }, "type": "object" }, "type": "array", "description": "Provenance of every change; never the previous values." }, "undo": { "properties": { "available": { "type": "boolean" }, "problems": { "items": { "properties": { "code": { "type": "string" } }, "type": "object", "required": [ "code" ] }, "type": "array" }, "until": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "featureEnabled": { "type": "boolean" }, "etag": { "type": "string", "description": "If-Match of its actions." } }, "type": "object", "required": [ "id", "entity", "status", "mutations", "undo", "taskIds", "etag" ], "title": "ApiMergeOperation" }, "ApiMergePage": { "properties": { "entity": { "type": [ "string", "null" ] }, "recordId": { "type": [ "string", "null" ] }, "canonicalId": { "type": [ "string", "null" ] }, "items": { "items": { "properties": { "id": { "type": [ "string", "null" ] }, "operationId": { "type": [ "string", "null" ] }, "entity": { "type": "string", "enum": [ "contact", "company" ] }, "sourceId": { "type": "string" }, "sourceName": { "type": [ "string", "null" ] }, "survivorId": { "type": "string" }, "survivorName": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "completed", "undone" ] }, "mergedAt": { "type": [ "string", "null" ], "format": "date-time" }, "actorId": { "type": [ "string", "null" ] }, "actorName": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "reviewPending": { "type": "boolean" }, "reviewedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewedByName": { "type": [ "string", "null" ] }, "undoUntil": { "type": [ "string", "null" ], "format": "date-time" }, "undoneAt": { "type": [ "string", "null" ], "format": "date-time" }, "undoneByName": { "type": [ "string", "null" ] }, "undoAvailable": { "type": "boolean" }, "undoUnavailableReason": { "type": [ "string", "null" ] }, "counts": { "type": "object" }, "actions": { "items": { "properties": { "code": { "type": "string" }, "count": { "type": "integer" } }, "type": "object" }, "type": "array" }, "legacy": { "type": "boolean", "description": "Merged before the journal existed (no operation)." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "Tasks of this resource (crm.duplicate_review / crm.merge_review)." } }, "type": "object", "required": [ "id", "entity", "status", "taskIds" ], "description": "Names of contacts only when the source may read them and reaches the kept contact." }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ], "description": "Send it as cursor for the next page (same filters)." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiMergePage" }, "ApiPageDomain": { "properties": { "id": { "type": "string" }, "hostname": { "type": "string", "description": "IDNA, lower case." }, "displayHostname": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verified", "active", "lost", "suspended" ] }, "verified": { "type": "boolean" }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dns": { "properties": { "txt": { "type": [ "boolean", "null" ] }, "routing": { "type": [ "boolean", "null" ] }, "routingVia": { "type": [ "string", "null" ] }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "lastCheckedAt": { "type": [ "string", "null" ], "format": "date-time" }, "nextCheckAt": { "type": [ "string", "null" ], "format": "date-time" }, "ownershipLostAt": { "type": [ "string", "null" ], "format": "date-time" }, "graceEndsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "End of the 72 h grace after a failed re-check." }, "tlsReady": { "type": "boolean" }, "tlsReadyAt": { "type": [ "string", "null" ], "format": "date-time" }, "operatorHold": { "type": "boolean" }, "operatorHoldAt": { "type": [ "string", "null" ], "format": "date-time" }, "defaultPageId": { "type": [ "string", "null" ] }, "defaultPage": { "type": [ "object", "null" ] }, "revision": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verification": { "properties": { "txt": { "properties": { "type": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "routing": { "items": { "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "value": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object", "description": "The records to publish, without the token." }, "taskId": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "open", "waiting", "needs_review", "done" ] }, "signals": { "items": { "type": "string", "enum": [ "verification_lost" ] }, "type": "array" }, "etag": { "type": "string", "description": "W/\"\": the If-Match of the actions." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "hostname", "status", "verified", "revision", "taskId", "taskStatus", "etag", "actions" ], "title": "ApiPageDomain", "description": "A custom domain of the hosted pages (its task is marketing.page_domain:). The ETag is W/\"\". Never the verification token: only the names of the records to publish." }, "ApiPageDomainPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiPageDomain" }, "type": "array", "description": "Oldest first." }, "total": { "type": "integer" }, "limit": { "type": "integer", "description": "Domains per company." }, "settings": { "type": "object", "description": "TLS mode, routing target and IPs, record prefixes, re-check and grace." } }, "type": "object", "required": [ "items", "total", "limit" ], "title": "ApiPageDomainPage" }, "ApiPipelines": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "archived": { "type": "boolean" }, "configurationRevision": { "type": "integer" }, "stages": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string", "enum": [ "open", "won", "lost" ] }, "canonicalStage": { "type": "string", "enum": [ "lead", "qualified", "proposal", "negotiation", "won", "lost" ] }, "probability": { "type": "integer" }, "position": { "type": "integer" }, "archived": { "type": "boolean" }, "requiredFieldKeys": { "items": { "type": "string" }, "type": "array" }, "importantFieldKeys": { "items": { "type": "string" }, "type": "array" }, "idleWarningDays": { "type": [ "integer", "null" ] }, "stageWarningDays": { "type": [ "integer", "null" ] } }, "type": "object" }, "type": "array", "description": "In board order, archived ones too." } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "items" ], "title": "ApiPipelines" }, "ApiPlaybook": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string", "enum": [ "es", "en" ] }, "state": { "type": "string", "enum": [ "published" ] }, "templateKey": { "type": [ "string", "null" ] }, "revision": { "type": "integer", "description": "The ETag is W/\"\"." }, "currentVersion": { "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedById": { "type": [ "string", "null" ] }, "publishedByName": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "questionCount": { "type": "integer" }, "sessionCounts": { "properties": { "draft": { "type": "integer" }, "completed": { "type": "integer" }, "abandoned": { "type": "integer" } }, "type": "object" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "version": { "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedById": { "type": [ "string", "null" ] }, "publishedByName": { "type": [ "string", "null" ] }, "playbookId": { "type": "string" }, "schemaVersion": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string", "enum": [ "es", "en" ] }, "definition": { "type": "object" }, "questionCount": { "type": "integer" } }, "type": [ "object", "null" ], "description": "Detail only. The published version: its definition (sections, questions with their types, options, conditions and mapped custom fields)." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "Always empty: the sessions are the tasks." } }, "type": "object", "required": [ "id", "name", "state", "revision", "currentVersion", "taskIds" ], "title": "ApiPlaybook", "description": "A published sales playbook (configuration: only administrators edit it, in the UI)." }, "ApiPlaybookPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiPlaybook" }, "type": "array", "description": "By name." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore", "total" ], "title": "ApiPlaybookPage" }, "ApiPlaybookSession": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string", "description": "crm.playbook_session:." }, "playbookId": { "type": "string" }, "versionId": { "type": "string", "description": "The pinned version." }, "versionNumber": { "type": [ "integer", "null" ] }, "playbookName": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "draft", "completed", "abandoned" ] }, "status": { "type": "string", "enum": [ "in_progress", "done", "cancelled" ], "description": "The normalized status of its task." }, "revision": { "type": "integer" }, "contactId": { "type": "string", "description": "The contact the session was opened for." }, "canonicalContactId": { "type": "string", "description": "The kept record when that contact was merged." }, "contactName": { "type": [ "string", "null" ], "description": "Only when the source may read the name and reaches the contact." }, "contactMerged": { "type": "boolean" }, "dealId": { "type": [ "string", "null" ] }, "dealTitle": { "type": [ "string", "null" ] }, "activityId": { "type": [ "string", "null" ] }, "activityTitle": { "type": [ "string", "null" ] }, "companyId": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "ownerId": { "type": [ "string", "null" ], "description": "Who opened it (the assignee)." }, "ownerName": { "type": [ "string", "null" ] }, "createdById": { "type": [ "string", "null" ] }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedByName": { "type": [ "string", "null" ] }, "abandonedAt": { "type": [ "string", "null" ], "format": "date-time" }, "abandonedByName": { "type": [ "string", "null" ] }, "abandonReason": { "type": [ "string", "null" ] }, "conflictCount": { "type": "integer", "description": "Completions refused because a field changed after the preview." }, "progress": { "properties": { "visible": { "type": "integer" }, "answered": { "type": "integer" }, "required": { "type": "integer" }, "requiredAnswered": { "type": "integer" }, "missingRequired": { "items": { "type": "string" }, "type": "array", "description": "Detail only." }, "hiddenQuestionIds": { "items": { "type": "string" }, "type": "array", "description": "Detail only." }, "hiddenAnswered": { "items": { "type": "string" }, "type": "array", "description": "Detail only." } }, "type": "object" }, "answers": { "type": "object", "description": "Detail only: answers keyed by question ID. The answer to a question mapped to a custom field of the contact is null when this source may not read that field (customValues, allowedCustomFields or the contact's reach), as in the completion preview." }, "redactedQuestionIds": { "items": { "type": "string" }, "type": "array", "description": "Detail only: questions with a saved answer this source may not read (null in answers), in question order. Sending that null back in a save keeps the saved answer." }, "notes": { "type": "string", "description": "Detail only: plain-text notes of the session." }, "version": { "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedById": { "type": [ "string", "null" ] }, "publishedByName": { "type": [ "string", "null" ] }, "playbookId": { "type": "string" }, "schemaVersion": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string", "enum": [ "es", "en" ] }, "definition": { "type": "object" }, "questionCount": { "type": "integer" } }, "type": [ "object", "null" ], "description": "Detail only. The published version: its definition (sections, questions with their types, options, conditions and mapped custom fields)." }, "effects": { "items": { "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "field_updated", "note_created", "activity_created", "activity_completed" ] }, "targetEntity": { "type": "string" }, "targetId": { "type": "string" }, "fieldId": { "type": [ "string", "null" ] }, "fieldLabel": { "type": [ "string", "null" ] }, "fieldType": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array", "description": "Detail only: receipts of the completion (never the values)." }, "completion": { "properties": { "noteId": { "type": [ "string", "null" ] }, "nextActivityId": { "type": [ "string", "null" ] }, "completedActivityId": { "type": [ "string", "null" ] }, "completeActivity": { "type": "boolean" }, "fields": { "items": { "type": "object" }, "type": "array" } }, "type": [ "object", "null" ], "description": "Detail only: what the completion created." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The session's own task." } }, "type": "object", "required": [ "id", "taskId", "playbookId", "versionId", "state", "status", "revision", "contactId", "taskIds" ], "title": "ApiPlaybookSession", "description": "A playbook session (its task is crm.playbook_session:). The ETag is W/\"\"." }, "ApiPlaybookSessionPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiPlaybookSession" }, "type": "array", "description": "Newest first; without answers or notes (read the session)." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore", "total" ], "title": "ApiPlaybookSessionPage" }, "ApiReportAttribution": { "properties": { "policy": { "type": "object" }, "model": { "type": "string" }, "period": { "type": "object" }, "campaigns": { "items": { "type": "object" }, "type": "array" }, "verifiedPayments": { "type": "object" } }, "additionalProperties": true, "type": "object", "title": "ApiReportAttribution", "description": "Attribution per campaign (first or last touch, 30-day window) with its funnel and money per currency, never mixed nor converted. The same JSON as the app's screen for the same parameters." }, "ApiReportCampaign": { "properties": { "channel": { "type": "string" }, "links": { "items": { "type": "object" }, "type": "array" }, "variations": { "items": { "type": "object" }, "type": "array" }, "roles": { "items": { "type": "object" }, "type": "array" }, "experiment": { "type": [ "object", "null" ] } }, "additionalProperties": true, "type": "object", "title": "ApiReportCampaign", "description": "Aggregated results of one campaign (accepted, delivered, opens, clicks, bounces…), its links and the A/B report; push campaigns answer their own report; never recipients. The same JSON as the app's screen for the same parameters." }, "ApiReportCsatFunnel": { "properties": { "days": { "type": "integer" }, "basis": { "type": "string" }, "groupBy": { "type": "string" }, "filters": { "type": "object" }, "period": { "type": "object" }, "funnel": { "type": "object" }, "invitations": { "type": "object" }, "manual": { "type": "object" }, "csat": { "type": "object" }, "technical": { "type": "object" }, "groups": { "items": { "type": "object" }, "type": "array" } }, "additionalProperties": true, "type": "object", "required": [ "funnel", "csat" ], "title": "ApiReportCsatFunnel", "description": "CSAT survey funnel: closes, eligibility, omissions by reason, invitations, coverage, answer rate, manual links apart, CSAT with n and distribution, technical replies and groups. The same JSON as the app's screen for the same parameters." }, "ApiReportDashboard": { "properties": { "inbox": { "properties": { "unresolved": { "type": "integer" }, "pending": { "type": "integer" } }, "type": "object" }, "documentCount": { "type": "integer" }, "documentCountByAgent": { "additionalProperties": { "type": "integer" }, "type": "object" }, "stats": { "properties": { "openConversations": { "type": "integer" }, "pendingHandoffs": { "type": "integer" }, "automatedToday": { "type": "integer" }, "totalContacts": { "type": "integer" } }, "type": "object" }, "volume": { "items": { "type": "object", "description": "day and one counter per channel." }, "type": "array" }, "recentConversations": { "items": { "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": [ "string", "null" ] }, "assigneeId": { "type": [ "string", "null" ] }, "assigneeName": { "type": [ "string", "null" ] }, "unreadCount": { "type": "integer" }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "purpose": { "type": "string" }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "The contact as this source may see it: its read fields, or only its ID when the source only reaches the contacts linked to it." }, "preview": { "type": [ "string", "null" ], "description": "The last message; only with support:content." }, "subject": { "type": [ "string", "null" ], "description": "Only with support:content." } }, "type": "object" }, "type": "array" } }, "additionalProperties": true, "type": "object", "required": [ "inbox", "stats", "volume", "recentConversations" ], "title": "ApiReportDashboard", "description": "Inbox counters, documents, today's automation, contacts, the volume of the last 7 local days by channel and the 5 latest conversations. The same JSON as the app's screen for the same parameters." }, "ApiReportSales": { "properties": { "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "timezone": { "type": "string" }, "groupBy": { "type": "string" }, "coverage": { "properties": { "trackedDeals": { "type": "integer" }, "untrackedDeals": { "type": "integer" }, "firstRecordedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "history": { "items": { "type": "object" }, "type": "array" }, "current": { "items": { "type": "object" }, "type": "array" } }, "additionalProperties": true, "type": "object", "required": [ "history", "current" ], "title": "ApiReportSales", "description": "Recorded deal history by owner, stage, date or source (UTC) and the current snapshot by owner and stage. The same JSON as the app's screen for the same parameters." }, "ApiReportSalesForecast": { "properties": { "formulaVersion": { "type": "string" }, "asOf": { "type": "string" }, "timezone": { "type": "string" }, "today": { "type": "string" } }, "additionalProperties": true, "type": "object", "title": "ApiReportSalesForecast", "description": "Forecast of one period: net won, weighted pipeline by category, undated and overdue apart, projection and the goals of the period. The same JSON as the app's screen for the same parameters." }, "ApiReportSalesGoals": { "properties": { "items": { "items": { "type": "object" }, "type": "array" }, "total": { "type": "integer" }, "canManage": { "type": "boolean" } }, "additionalProperties": true, "type": "object", "title": "ApiReportSalesGoals", "description": "Sales goals with the progress of the period containing periodDate (canManage is always false for a key). The same JSON as the app's screen for the same parameters." }, "ApiReportSalesInsight": { "properties": { "report": { "type": "string" }, "formulaVersion": { "type": "string" }, "asOf": { "type": "string" }, "timezone": { "type": "string" }, "period": { "type": "object" }, "filters": { "type": "object" }, "coverage": { "type": "object" } }, "additionalProperties": true, "type": "object", "title": "ApiReportSalesInsight", "description": "One sales insight (conversion, duration, progress or results) with its period, cut-off, zone, filters, formula and coverage; never the records behind a cell. The same JSON as the app's screen for the same parameters." }, "ApiReportSequences": { "properties": { "mode": { "type": "string" }, "groupBy": { "type": "string" }, "period": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "timezone": { "type": "string" } }, "additionalProperties": true, "type": "object", "title": "ApiReportSequences", "description": "Results of the sales sequences by cohort or by events, grouped by version, salesperson or period; rates are null without sample. The same JSON as the app's screen for the same parameters." }, "ApiReportSupport": { "properties": { "days": { "type": "integer" }, "groupBy": { "type": "string" }, "generatedAt": { "type": "string" }, "cohortStart": { "type": "string" }, "summary": { "type": "object" }, "groups": { "items": { "type": "object" }, "type": "array" }, "surveysCreated": { "type": "integer" }, "feedback": { "items": { "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "rating": { "type": [ "integer", "null" ] }, "respondedAt": { "type": [ "string", "null" ], "format": "date-time" }, "feedback": { "type": [ "string", "null" ], "description": "The customer's comment; only with support:content." } }, "type": "object" }, "type": "array" } }, "additionalProperties": true, "type": "object", "required": [ "summary", "groups" ], "title": "ApiReportSupport", "description": "Support conversations created in the last N days by channel, agent, inbox, team or label: volume, first reply, resolution and CSAT. The same JSON as the app's screen for the same parameters." }, "ApiReportSupportLive": { "properties": { "generatedAt": { "type": "string" }, "open": { "type": "integer" }, "pending": { "type": "integer" }, "unassigned": { "type": "integer" }, "recent": { "items": { "properties": { "id": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "assignee": { "type": [ "string", "null" ] }, "contact": { "type": [ "string", "null" ], "description": "The contact's name, only when this source may read it." }, "subject": { "type": [ "string", "null" ], "description": "Only with support:content." } }, "type": "object" }, "type": "array" } }, "additionalProperties": true, "type": "object", "required": [ "open", "pending", "unassigned", "recent" ], "title": "ApiReportSupportLive", "description": "Open, pending and unassigned support conversations now and the 20 latest open ones. The same JSON as the app's screen for the same parameters." }, "ApiSalesMailboxPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "ownerId": { "type": "string" }, "ownerName": { "type": [ "string", "null" ] }, "ownerActive": { "type": "boolean" }, "provider": { "type": "string", "enum": [ "gmail", "microsoft" ] }, "status": { "type": "string", "enum": [ "pending", "ready", "paused", "revoked" ] }, "statusReason": { "type": [ "string", "null" ] }, "usable": { "type": "boolean" }, "unusableReason": { "type": [ "string", "null" ] }, "reconnectRequired": { "type": "boolean" }, "authorizationGeneration": { "type": "integer" }, "acceptedAt": { "type": [ "string", "null" ], "format": "date-time" }, "connectedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastCheckOkAt": { "type": [ "string", "null" ], "format": "date-time" }, "checkFresh": { "type": "boolean" }, "revokedAt": { "type": [ "string", "null" ], "format": "date-time" }, "timezone": { "type": "string" }, "workingHours": { "type": "object" }, "hasSignature": { "type": "boolean" }, "hasCalendar": { "type": "boolean" }, "revision": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks of the record (sales.enrollment:…)." }, "appUrl": { "type": [ "string", "null" ] } }, "type": "object", "required": [ "id", "ownerId", "provider", "status", "usable", "taskIds" ], "description": "A salesperson's sales mailbox: owner and state; never the address, signature or tokens. Reconnecting is done by its owner in the app (appUrl)." }, "type": "array" }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore", "total" ], "title": "ApiSalesMailboxPage" }, "ApiSalesSequence": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string", "enum": [ "es", "en" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "revision": { "type": "integer" }, "stepCounts": { "properties": { "email": { "type": "integer" }, "task": { "type": "integer" }, "wait": { "type": "integer" }, "branch": { "type": "integer" }, "end": { "type": "integer" }, "sms": { "type": "integer" } }, "type": "object" }, "totalDays": { "type": "integer" }, "createdById": { "type": [ "string", "null" ] }, "createdByName": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "latestVersion": { "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "emailSteps": { "type": "integer" }, "taskSteps": { "type": "integer" }, "totalWaitDays": { "type": "integer" } }, "type": [ "object", "null" ] }, "hasUnpublishedChanges": { "type": "boolean" }, "activeEnrollments": { "type": "integer" }, "enrollable": { "type": "boolean", "description": "Published: it accepts enrollments." }, "version": { "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "emailSteps": { "type": "integer" }, "taskSteps": { "type": "integer" }, "totalWaitDays": { "type": "integer" }, "language": { "type": "string" }, "purpose": { "type": "string" }, "stopRules": { "type": "object" }, "window": { "type": [ "object", "null" ] }, "variables": { "items": { "type": "string" }, "type": "array" }, "steps": { "items": { "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "email", "task", "wait", "branch", "end", "sms" ], "description": "email and sms (delayDays; never the body), task, wait (days), branch (a condition that picks a path) and end (ends a path)." }, "position": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "threadMode": { "type": [ "string", "null" ] }, "delayDays": { "type": [ "integer", "null" ] }, "kind": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "dueDays": { "type": [ "integer", "null" ] }, "waitForCompletion": { "type": [ "boolean", "null" ] }, "days": { "type": [ "integer", "null" ] }, "conditionKind": { "type": [ "string", "null" ], "enum": [ "hasPhone", "smsAllowed", "contactMatches", "opportunityOpen", "opportunityInStage", null ], "description": "branch: what the condition checks (never its filters or stages)." }, "ifTrue": { "type": [ "string", "null" ], "description": "branch: \"\" the next step, null ends the path, or the ID of a later step." }, "ifFalse": { "type": [ "string", "null" ], "description": "branch: like ifTrue." } }, "type": "object" }, "type": "array" } }, "type": [ "object", "null" ], "description": "Detail only: the published version, the structure of its steps (email subjects and task titles; never bodies)." }, "versions": { "items": { "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "emailSteps": { "type": "integer" }, "taskSteps": { "type": "integer" }, "totalWaitDays": { "type": "integer" } }, "type": [ "object", "null" ] }, "type": "array", "description": "Detail only: every published version." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "Always empty: a sequence is not a task." } }, "type": "object", "required": [ "id", "name", "status", "revision", "enrollable", "taskIds" ], "title": "ApiSalesSequence", "description": "A sales sequence (authoring stays in the app). The ETag is W/\"\"." }, "ApiSalesSequencePage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiSalesSequence" }, "type": "array", "description": "Newest change first." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore", "total" ], "title": "ApiSalesSequencePage" }, "ApiSegmentPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "filters": { "type": "object", "description": "The saved filters (ContactFilters). q, company and the values of rules on name, email, phone, company or custom fields are null unless the key reads those fields of every contact (contacts:read, contactScope company and the source's read fields)." }, "hiddenFilters": { "items": { "type": "string", "enum": [ "q", "company", "rules" ] }, "type": "array", "description": "Filters whose values are hidden from this key; preview the segment by segmentId." }, "behavior": { "type": "boolean", "description": "It has behavior conditions (marketing.behavior)." } }, "type": "object" }, "type": "array", "description": "By name." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" }, "behaviorEnabled": { "type": "boolean", "description": "marketing.behavior is on for the company." } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiSegmentPage" }, "ApiSegmentPreview": { "properties": { "segmentId": { "type": [ "string", "null" ] }, "count": { "type": "integer" }, "evaluatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "settleSeconds": { "type": "integer" }, "behavior": { "type": "boolean" }, "coverageSince": { "type": [ "string", "null" ], "format": "date-time" }, "windowBeforeCoverage": { "type": "boolean" }, "insufficientHistory": { "type": [ "integer", "null" ] }, "tooLarge": { "type": "boolean" }, "maxMembers": { "type": "integer" }, "fingerprint": { "type": "string", "description": "Informative: evaluatedAt and a hash of the members." }, "purchaseCoverage": { "type": [ "object", "null" ] } }, "type": "object", "required": [ "count", "evaluatedAt", "fingerprint" ], "title": "ApiSegmentPreview", "description": "Counts, coverage and the fingerprint of the SEG-02 preview; never contacts." }, "ApiSequenceEnrollAnswer": { "properties": { "runId": { "type": "string" }, "sequenceId": { "type": "string" }, "action": { "type": "string", "enum": [ "enroll" ] }, "dryRun": { "type": "boolean" }, "outcome": { "type": "string", "enum": [ "succeeded" ] }, "replayed": { "type": "boolean" }, "valid": { "type": "boolean", "description": "dryRun only." }, "result": { "properties": { "requestId": { "type": "string" }, "versionId": { "type": "string" }, "versionNumber": { "type": "integer" }, "mailboxId": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "enrolled": { "type": "integer" }, "rejected": { "type": "integer" }, "results": { "items": { "properties": { "contactId": { "type": "string" }, "status": { "type": "string", "enum": [ "eligible", "rejected", "enrolled" ] }, "eligible": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "message": { "type": [ "object", "null" ] }, "enrollmentId": { "type": "string" }, "canonicalId": { "type": "string" }, "until": { "type": [ "string", "null" ], "format": "date-time" }, "variables": { "items": { "type": "string" }, "type": "array" }, "detail": { "type": "string" }, "holder": { "type": "object", "description": "The live enrollment that holds the contact." } }, "type": "object" }, "type": "array" } }, "type": "object", "description": "Execution: the request with one result per contact." }, "preview": { "properties": { "blocking": { "items": { "type": "object" }, "type": "array" }, "counts": { "properties": { "eligible": { "type": "integer" }, "rejected": { "type": "integer" }, "requested": { "type": "integer" } }, "type": "object" }, "results": { "items": { "properties": { "contactId": { "type": "string" }, "status": { "type": "string", "enum": [ "eligible", "rejected", "enrolled" ] }, "eligible": { "type": "boolean" }, "code": { "type": [ "string", "null" ] }, "message": { "type": [ "object", "null" ] }, "enrollmentId": { "type": "string" }, "canonicalId": { "type": "string" }, "until": { "type": [ "string", "null" ], "format": "date-time" }, "variables": { "items": { "type": "string" }, "type": "array" }, "detail": { "type": "string" }, "holder": { "type": "object", "description": "The live enrollment that holds the contact." } }, "type": "object" }, "type": "array" }, "canEnroll": { "type": "boolean" } }, "type": "object", "description": "dryRun: mailbox state, blocking problems, the first action, counts and one result per contact (eligible or the reason of the exclusion)." }, "confirm": { "properties": { "previewFingerprint": { "type": "string" } }, "type": "object", "description": "dryRun: the fingerprint of what the preview showed." } }, "type": "object", "title": "ApiSequenceEnrollAnswer" }, "ApiSequenceEnrollment": { "properties": { "id": { "type": "string" }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks of the record (sales.enrollment:…)." }, "sequenceId": { "type": "string" }, "sequenceName": { "type": [ "string", "null" ] }, "versionId": { "type": "string" }, "versionNumber": { "type": "integer" }, "contactId": { "type": "string" }, "contactName": { "type": [ "string", "null" ], "description": "Only with the source's read field name and reach." }, "contactMerged": { "type": "boolean" }, "dealId": { "type": [ "string", "null" ] }, "dealTitle": { "type": [ "string", "null" ] }, "ownerId": { "type": "string", "description": "The salesperson who owns the mailbox (the assignee)." }, "ownerName": { "type": [ "string", "null" ] }, "mailboxId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "waiting_time", "waiting_task", "paused", "delivery_uncertain", "stopped_reply", "stopped_meeting", "stopped_optout", "stopped_bounce", "stopped_goal", "cancelled", "completed" ] }, "live": { "type": "boolean" }, "pauseReason": { "type": [ "string", "null" ], "enum": [ "mailbox", "sender", "sync", "billing", "feature", "contact_changed", "opportunity_closed", "preference", "auto_reply", "possible_reply", "manual_followup", "sequence", "manual", "delivery", "task", "meeting", "account_reply", null ], "description": "Why it is paused. account_reply: another person of the same customer company replied and the company's coordination policy paused the account's other enrollments (the owner resumes it)." }, "endReason": { "type": [ "string", "null" ] }, "currentStep": { "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "position": { "type": "integer" } }, "type": [ "object", "null" ] }, "totalSteps": { "type": [ "integer", "null" ] }, "nextRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "timezone": { "type": "string" }, "workingHours": { "type": "object" }, "conversationId": { "type": [ "string", "null" ] }, "runNumber": { "type": "integer" }, "revision": { "type": "integer" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "steps": { "items": { "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "position": { "type": "integer" }, "state": { "type": "string", "enum": [ "passed", "current", "pending", "not_taken" ], "description": "not_taken: a step of another path of a condition (branch) that this enrollment did not take." }, "subject": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "days": { "type": "integer" }, "executionId": { "type": [ "string", "null" ] }, "branchOutcome": { "type": [ "string", "null" ], "enum": [ "true", "false", null ], "description": "branch: the path the condition chose (null until it is evaluated and for other steps)." } }, "type": "object" }, "type": "array", "description": "Detail only." }, "executions": { "items": { "properties": { "id": { "type": "string" }, "stepId": { "type": "string" }, "position": { "type": "integer" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "claimed", "accepted", "waiting_task", "done", "skipped", "cancelled", "failed_definitive", "uncertain" ] }, "errorCode": { "type": [ "string", "null" ] }, "activityId": { "type": [ "string", "null" ] }, "activityTaskId": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ] }, "conversationId": { "type": [ "string", "null" ] }, "scheduledAt": { "type": [ "string", "null" ], "format": "date-time" }, "availableAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "attempts": { "items": { "type": "object" }, "type": "array" }, "branchOutcome": { "type": [ "string", "null" ], "enum": [ "true", "false", null ], "description": "Evaluation of a condition (type branch): true or false." } }, "type": "object" }, "type": "array", "description": "Detail only: what each step did (states, codes, IDs and dates)." }, "currentExecutionId": { "type": [ "string", "null" ] }, "resume": { "type": [ "object", "null" ], "description": "Detail of a paused enrollment: whether resuming is possible now and the typed problems that block it." }, "decisions": { "items": { "type": "object" }, "type": "array", "description": "Detail only: the ledger of decisions (who, what, when; never reasons)." }, "limits": { "type": "object" } }, "type": "object", "required": [ "id", "taskIds", "sequenceId", "contactId", "ownerId", "status", "revision" ], "title": "ApiSequenceEnrollment", "description": "A contact enrolled in a sales sequence (its task is sales.enrollment: while it needs attention). The ETag is W/\"\". Never the recipient or mailbox address." }, "ApiSequenceEnrollmentPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiSequenceEnrollment" }, "type": "array", "description": "Newest first; without steps or executions (read the enrollment)." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore", "total" ], "title": "ApiSequenceEnrollmentPage" }, "ApiSignupForm": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "open", "needs_review", "done", "cancelled" ] }, "name": { "type": "string" }, "title": { "type": "string" }, "connectionId": { "type": [ "string", "null" ] }, "purpose": { "type": "string" }, "policyVersion": { "type": "string" }, "policyText": { "type": "string" }, "enabled": { "type": "boolean" }, "connectionReady": { "type": "boolean" }, "publicPath": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "publicId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "paused", "archived" ] }, "revision": { "type": "integer" }, "operatorHold": { "type": "boolean", "description": "Withdrawn by the platform operator: read only." }, "operatorHoldAt": { "type": [ "string", "null" ], "format": "date-time" }, "embedOrigins": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "embedAnywhere": { "type": "boolean" }, "publishedVersion": { "type": [ "object", "null" ] }, "hasUnpublishedChanges": { "type": "boolean" }, "pagePath": { "type": [ "string", "null" ] }, "pageUrl": { "type": [ "string", "null" ] }, "legacyUrl": { "type": [ "string", "null" ] }, "publicUrl": { "type": [ "string", "null" ] }, "pagesMode": { "type": "string" }, "pagesOriginSeparate": { "type": "boolean" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "layout": { "type": "string" }, "purposes": { "items": { "type": "object" }, "type": [ "array", "null" ] }, "customDomainId": { "type": [ "string", "null" ] }, "indexable": { "type": [ "boolean", "null" ] }, "pageDomain": { "type": [ "object", "null" ] }, "indexed": { "type": "boolean" }, "etag": { "type": "string", "description": "W/\"\": the If-Match of the actions." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "status", "revision", "taskId", "taskStatus", "etag", "actions" ], "title": "ApiSignupForm", "description": "A signup form and its hosted page (its task is marketing.form_publication:). The ETag is W/\"\". Never the iframe snippet nor the blocks of the page editor." }, "ApiSignupFormPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiSignupForm" }, "type": "array", "description": "Newest first." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiSignupFormPage" }, "ApiSignupFormVersions": { "properties": { "formId": { "type": "string" }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "version": { "type": "integer" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "current": { "type": "boolean" }, "publishedBy": { "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "title": { "type": [ "string", "null" ] }, "policyVersion": { "type": [ "string", "null" ] } }, "type": "object" }, "type": "array", "description": "Published versions, newest first (at most 50)." } }, "type": "object", "required": [ "formId", "items" ], "title": "ApiSignupFormVersions" }, "ApiSite": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string" }, "taskStatus": { "type": "string", "enum": [ "open", "done", "cancelled" ] }, "signals": { "items": { "type": "string", "enum": [ "verification_lost" ] }, "type": "array" }, "publicId": { "type": "string" }, "name": { "type": "string" }, "origin": { "type": "string" }, "allowedPaths": { "items": { "type": "string" }, "type": "array" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "verified": { "type": "boolean" }, "verifiedOrigin": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "trackingEnabled": { "type": "boolean" }, "attributionEnabled": { "type": "boolean" }, "pushEnabled": { "type": "boolean" }, "configRevision": { "type": "integer" }, "lastConfigAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastEventAt": { "type": [ "string", "null" ], "format": "date-time" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "verification": { "properties": { "type": { "type": "string" }, "name": { "type": [ "string", "null" ], "description": "_aiocrm-verify.: where the administrator publishes the code." } }, "type": "object" }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of the actions." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object", "required": [ "id", "name", "origin", "status", "verified", "taskId", "taskStatus", "etag", "actions" ], "title": "ApiSite", "description": "A website of the company (its task is marketing.site_verification:). The ETag is synthetic (W/\"h:…\"). Never the verification code: only the name of the TXT record." }, "ApiSitePage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiSite" }, "type": "array", "description": "Archived ones last." }, "total": { "type": "integer" }, "activeCount": { "type": [ "integer", "null" ], "description": "Sites that are not archived." }, "maxSites": { "type": [ "integer", "null" ] }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiSitePage" }, "ApiSupportLabels": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "items" ], "title": "ApiSupportLabels" }, "ApiSupportMacros": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "actions": { "type": "object", "description": "status, priority, assigneeId, addLabelIds and removeLabelIds." } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "items" ], "title": "ApiSupportMacros" }, "ApiSupportOverview": { "properties": { "policy": { "type": "object", "description": "Assignment, opening hours and SLA targets of the company." }, "isOpen": { "type": "boolean", "description": "Within the opening hours now." }, "teams": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "channels": { "items": { "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "memberIds": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" }, "agents": { "items": { "properties": { "userId": { "type": "string" }, "name": { "type": "string" }, "availability": { "type": "string", "enum": [ "online", "away", "offline" ] }, "capacity": { "type": "integer" }, "load": { "type": "integer" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "policy", "isOpen", "teams", "agents" ], "title": "ApiSupportOverview" }, "ApiSupportTeams": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "channels": { "items": { "type": "string" }, "type": "array" }, "enabled": { "type": "boolean" }, "memberIds": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "items" ], "title": "ApiSupportTeams" }, "ApiTask": { "properties": { "id": { "type": "string", "description": ":, at most 200 of A-Z a-z 0-9 . _ : -" }, "kind": { "type": "string" }, "area": { "type": "string", "enum": [ "contacts", "companies", "deals", "activities", "sequences", "playbooks", "duplicates", "support", "csat", "voice", "calendar", "campaigns", "journeys", "segments", "forms", "sites", "conversions", "knowledge", "channels", "reports", "team", "webhooks", "automation" ] }, "schemaVersion": { "type": "integer" }, "title": { "type": "string", "description": "Native title or one generated in es/en (Accept-Language); never a message body." }, "description": { "type": "string", "description": "Only when it is not a customer's text or the key has :content." }, "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "needs_review", "done", "cancelled" ] }, "sourceStatus": { "type": [ "string", "null" ] }, "signals": { "items": { "type": "string", "enum": [ "overdue", "due_soon", "decision_due", "unassigned", "unread", "handoff", "ai_handling", "ai_review", "snoozed", "sla_response_at_risk", "sla_response_breached", "sla_resolution_at_risk", "sla_resolution_breached", "sla_escalated", "missing_fields", "stale_stage", "no_next_activity", "close_date_passed", "uncertain", "failed", "error", "reconnect_required", "verification_lost", "merge_blocked", "inconclusive" ] }, "type": "array" }, "priority": { "type": [ "string", "null" ], "enum": [ "low", "normal", "high", "urgent", null ] }, "assignee": { "properties": { "type": { "type": "string", "enum": [ "user", "routing_contact" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "team": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": [ "object", "null" ] }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" }, "dueKind": { "type": [ "string", "null" ], "enum": [ "due", "sla_first_response", "sla_resolution", "wake", "expected_close", "send_at", "decision_deadline", "undo_until", "next_run", "booking_start", "expires", null ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "links": { "items": { "properties": { "type": { "type": "string", "enum": [ "contact", "company", "deal", "activity", "ticket", "conversation", "campaign", "sequence", "enrollment", "playbook", "playbook_session", "automation", "form", "site", "booking", "voice_call", "knowledge_document", "channel_account", "webhook_endpoint", "merge_operation" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object", "required": [ "type", "id" ], "description": "A contact shows only the source's read fields, or only its id when the source cannot reach it. Showing any of its fields is a recorded read of the contact (one per key, contact and request)." }, "type": "array" }, "appUrl": { "type": [ "string", "null" ], "description": "Absolute link to the screen in RouterClip." }, "version": { "type": [ "integer", "null" ], "description": "Counter of observed changes (task index)." }, "etag": { "type": "string", "description": "W/\"\" or W/\"h:<16 hex>\": the If-Match of PATCH and actions." }, "editable": { "items": { "type": "string", "enum": [ "title", "description", "status", "sourceStatus", "priority", "dueAt", "assigneeId", "teamId", "category", "activityKind", "contactId", "dealId", "ticketId" ] }, "type": "array" }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array" }, "externalLink": { "properties": { "externalId": { "type": "string" }, "url": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the link of this source." } }, "type": "object", "required": [ "id", "kind", "area", "schemaVersion", "title", "status", "etag", "actions" ], "title": "ApiTask", "description": "A live projection of its source entity (API-TAREAS §2.4). Unknown fields, signals and reasons must be ignored." }, "ApiTaskActionAnswer": { "properties": { "runId": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "dryRun": { "type": "boolean" }, "outcome": { "type": "string", "enum": [ "succeeded", "accepted" ] }, "replayed": { "type": "boolean" }, "result": { "type": "object", "description": "Minimal: IDs, counts and tokens, never bodies." }, "task": { "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "etag": { "type": [ "string", "null" ] } }, "type": [ "object", "null" ] }, "valid": { "type": "boolean", "description": "dryRun only." }, "preview": { "type": "object", "description": "dryRun of an action with a native previous step." }, "confirm": { "type": "object", "description": "dryRun: the token(s) the execution needs." }, "effects": { "items": { "type": "string" }, "type": "array", "description": "dryRun without a native step: declared effects." } }, "type": "object", "title": "ApiTaskActionAnswer" }, "ApiTaskChanges": { "properties": { "items": { "items": { "properties": { "taskId": { "type": "string" }, "kind": { "type": "string" }, "change": { "type": "string", "enum": [ "upsert", "deleted" ] }, "status": { "type": "string", "enum": [ "open", "in_progress", "waiting", "needs_review", "done", "cancelled" ] }, "version": { "type": "integer", "description": "Discard a change whose version you already know." }, "changedAt": { "type": "string", "format": "date-time" } }, "type": "object", "required": [ "taskId", "kind", "change", "status", "version", "changedAt" ] }, "type": "array" }, "nextCursor": { "type": "string", "description": "Persist it after applying the items; it advances past hidden tasks." }, "hasMore": { "type": "boolean" }, "indexedThrough": { "type": "string", "format": "date-time" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiTaskChanges", "description": "The last state of every task changed after the cursor, in feed order (at least once)." }, "ApiTaskChangesCursor": { "properties": { "cursor": { "type": "string", "description": "The current position of the change feed: read it before the initial load." }, "indexedThrough": { "type": "string", "format": "date-time" } }, "type": "object", "required": [ "cursor" ], "title": "ApiTaskChangesCursor" }, "ApiTaskError": { "properties": { "detail": { "properties": { "code": { "type": "string", "description": "UPPER_CASE error code." }, "message": { "type": "string" }, "requestId": { "type": "string", "description": "The X-Request-ID of this answer." }, "field": { "type": "string", "description": "Path of the rejected field; values are never repeated." } }, "additionalProperties": true, "type": "object", "required": [ "code", "message" ] } }, "type": "object", "required": [ "detail" ], "title": "ApiTaskError" }, "ApiTaskExternalLink": { "properties": { "taskId": { "type": "string" }, "externalLink": { "properties": { "externalId": { "type": "string" }, "url": { "type": "string" } }, "type": "object" } }, "type": "object", "title": "ApiTaskExternalLink" }, "ApiTaskHistory": { "properties": { "taskId": { "type": "string" }, "items": { "items": { "properties": { "at": { "type": "string", "format": "date-time" }, "type": { "type": "string" }, "actor": { "properties": { "kind": { "type": "string", "enum": [ "user", "api", "system" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "changedFields": { "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object", "title": "ApiTaskHistory" }, "ApiTaskKinds": { "properties": { "catalogVersion": { "type": "integer" }, "schemaVersion": { "type": "integer" }, "statuses": { "items": { "type": "string" }, "type": "array" }, "signals": { "items": { "type": "string" }, "type": "array" }, "kinds": { "items": { "properties": { "kind": { "type": "string" }, "area": { "type": "string" }, "features": { "items": { "type": "string" }, "type": "array" }, "statuses": { "items": { "type": "string" }, "type": "array" }, "signals": { "items": { "type": "string" }, "type": "array" }, "patch": { "type": [ "object", "null" ] }, "creatable": { "type": "boolean" }, "completion": { "type": [ "string", "null" ] }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string" }, "preview": { "type": "boolean" }, "returns202": { "type": "boolean" }, "inputSchema": { "type": "object" } }, "type": "object" }, "type": "array" } }, "type": "object" }, "type": "array" } }, "type": "object", "title": "ApiTaskKinds" }, "ApiTaskList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiTask" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque and signed; bound to the company, source, filters and sort; valid 24 h." }, "hasMore": { "type": "boolean" }, "indexedThrough": { "type": "string", "format": "date-time", "description": "Changes before this moment are in the index." } }, "type": "object", "required": [ "items", "hasMore", "indexedThrough" ], "title": "ApiTaskList", "description": "Filters run on the task index (seconds behind); every item is hydrated live from its entity, and tasks that disappeared meanwhile are left out." }, "ApiTaskNoteAnswer": { "properties": { "taskId": { "type": "string" }, "note": { "type": "object" }, "replayed": { "type": "boolean" } }, "type": "object", "title": "ApiTaskNoteAnswer" }, "ApiTaskNotes": { "properties": { "taskId": { "type": "string" }, "items": { "items": { "type": "object" }, "type": "array" } }, "type": "object", "title": "ApiTaskNotes" }, "ApiTaskSummary": { "properties": { "total": { "type": "integer" }, "byKind": { "additionalProperties": { "type": "integer" }, "type": "object" }, "byStatus": { "additionalProperties": { "type": "integer" }, "type": "object" }, "byAssignee": { "items": { "properties": { "assignee": { "properties": { "type": { "type": "string" }, "id": { "type": "string" } }, "type": [ "object", "null" ] }, "count": { "type": "integer" } }, "type": "object" }, "type": "array" }, "indexedThrough": { "type": "string", "format": "date-time" } }, "type": "object", "required": [ "total", "byKind", "byStatus", "byAssignee" ], "title": "ApiTaskSummary" }, "ApiTaskWebhook": { "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "kinds": { "items": { "type": "string" }, "type": "array", "description": "Empty: every kind this source can read." }, "events": { "items": { "type": "string", "enum": [ "task.created", "task.updated", "task.completed", "task.deleted" ] }, "type": "array" }, "skipOwnChanges": { "type": "boolean", "description": "Changes caused only by this source are not delivered (echo suppression for two-way synchronization)." }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "manual", "receiver_gone", null ], "description": "receiver_gone: the receiver answered 410." }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "authorized": { "type": "boolean", "description": "The platform still authorizes the URL's origin." }, "hasSecret": { "type": "boolean" }, "secretRotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdVia": { "type": "string", "enum": [ "api", "admin" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "properties": { "pending": { "type": "integer" }, "failed": { "type": "integer" } }, "type": "object" }, "failureStreak": { "type": "integer", "description": "Failed attempts in a row. From 5 on the webhook waits and is then probed with one delivery at a time." }, "deferredUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "While set, the webhook waits after 5 failed attempts in a row (5 minutes, doubling up to an hour) without spending attempts. A test ping, a manual retry, a new URL or re-enabling it ends the wait." } }, "type": "object", "required": [ "id", "sourceId", "name", "url", "kinds", "events", "skipOwnChanges", "enabled" ], "title": "ApiTaskWebhook", "description": "A task webhook of this key's source. The secret is never listed: it comes only in the answer that creates the webhook or rotates its secret." }, "ApiTaskWebhookDeliveries": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiTaskWebhookDelivery" }, "type": "array" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "type": "object", "required": [ "items", "total" ], "title": "ApiTaskWebhookDeliveries" }, "ApiTaskWebhookDelivery": { "properties": { "id": { "type": "string", "description": "X-CRM-Delivery-Id (and Idempotency-Key): the same on every attempt." }, "endpointId": { "type": "string" }, "eventId": { "type": "string", "description": "X-CRM-Event-Id: the id of the payload." }, "type": { "type": "string", "enum": [ "task.created", "task.updated", "task.completed", "task.deleted", "ping" ] }, "taskId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "queued", "sending", "delivered", "failed" ] }, "attempts": { "type": "integer", "description": "Attempts of the current series (at most maxAttempts)." }, "totalAttempts": { "type": "integer" }, "maxAttempts": { "type": "integer" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastStatusCode": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object", "required": [ "id", "endpointId", "eventId", "type", "status", "attempts" ], "title": "ApiTaskWebhookDelivery" }, "ApiTaskWebhookList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiTaskWebhook" }, "type": "array" }, "limits": { "properties": { "perSource": { "type": "integer" }, "perCompany": { "type": "integer" }, "maxAttempts": { "type": "integer" } }, "type": "object" }, "sendEnabled": { "type": "boolean", "description": "API_TASK_WEBHOOKS_SEND_ENABLED: while false, deliveries wait queued." }, "events": { "items": { "type": "string", "enum": [ "task.created", "task.updated", "task.completed", "task.deleted" ] }, "type": "array" }, "readableKinds": { "items": { "type": "string" }, "type": "array", "description": "Kinds this key can read (and subscribe)." } }, "type": "object", "required": [ "items", "limits", "sendEnabled" ], "title": "ApiTaskWebhookList" }, "ApiTaskWebhookTest": { "properties": { "delivery": { "$ref": "#/components/schemas/ApiTaskWebhookDelivery" }, "sendEnabled": { "type": "boolean", "description": "While false the ping waits in the queue." } }, "type": "object", "required": [ "delivery", "sendEnabled" ], "title": "ApiTaskWebhookTest" }, "ApiTaskWebhookWithSecret": { "properties": { "id": { "type": "string" }, "sourceId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "kinds": { "items": { "type": "string" }, "type": "array", "description": "Empty: every kind this source can read." }, "events": { "items": { "type": "string", "enum": [ "task.created", "task.updated", "task.completed", "task.deleted" ] }, "type": "array" }, "skipOwnChanges": { "type": "boolean", "description": "Changes caused only by this source are not delivered (echo suppression for two-way synchronization)." }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "manual", "receiver_gone", null ], "description": "receiver_gone: the receiver answered 410." }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "authorized": { "type": "boolean", "description": "The platform still authorizes the URL's origin." }, "hasSecret": { "type": "boolean" }, "secretRotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdVia": { "type": "string", "enum": [ "api", "admin" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveries": { "properties": { "pending": { "type": "integer" }, "failed": { "type": "integer" } }, "type": "object" }, "failureStreak": { "type": "integer", "description": "Failed attempts in a row. From 5 on the webhook waits and is then probed with one delivery at a time." }, "deferredUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "While set, the webhook waits after 5 failed attempts in a row (5 minutes, doubling up to an hour) without spending attempts. A test ping, a manual retry, a new URL or re-enabling it ends the wait." }, "secret": { "type": "string", "description": "whsec_…: only when the webhook is created or its secret rotated. Store it now; it is never shown again." } }, "type": "object", "required": [ "id", "sourceId", "name", "url", "kinds", "events", "skipOwnChanges", "enabled", "secret" ], "title": "ApiTaskWebhookWithSecret", "description": "A task webhook just created or with its secret just rotated: the only answers that carry the secret." }, "ApiTicket": { "properties": { "id": { "type": "string" }, "taskId": { "type": "string", "description": "support.ticket:." }, "taskIds": { "items": { "type": "string" }, "type": "array" }, "conversationId": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "pending", "waiting_customer", "waiting_internal", "paused", "resolved" ], "description": "The native status of the ticket." }, "taskStatus": { "type": "string", "enum": [ "open", "in_progress", "waiting", "needs_review", "done", "cancelled" ], "description": "The normalized status (API-TAREAS §2.10)." }, "signals": { "items": { "type": "string", "enum": [ "unassigned", "unread", "handoff", "ai_handling", "ai_review", "snoozed", "sla_response_at_risk", "sla_response_breached", "sla_resolution_at_risk", "sla_resolution_breached", "sla_escalated" ] }, "type": "array" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "channel": { "type": "string" }, "teamId": { "type": [ "string", "null" ] }, "teamName": { "type": [ "string", "null" ] }, "assigneeId": { "type": [ "string", "null" ] }, "assigneeName": { "type": [ "string", "null" ] }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "pipelineId": { "type": [ "string", "null" ] }, "stageId": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ] }, "mergedIntoId": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "firstResponseApplicable": { "type": "boolean" }, "firstResponseDueAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolutionDueAt": { "type": [ "string", "null" ], "format": "date-time" }, "firstResponseAt": { "type": [ "string", "null" ], "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "responseBreached": { "type": "boolean" }, "resolutionBreached": { "type": "boolean" }, "slaEscalated": { "type": "boolean" }, "pausedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The SLA is paused since then (waiting statuses or the assistant's stage)." }, "aiHold": { "type": "boolean" }, "businessHoursSla": { "type": "boolean" }, "snoozedUntil": { "type": [ "string", "null" ], "format": "date-time" }, "customerActivityAt": { "type": [ "string", "null" ], "format": "date-time" }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" }, "dueKind": { "type": [ "string", "null" ], "enum": [ "wake", "sla_first_response", "sla_resolution", null ] }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of PATCH and actions." }, "description": { "type": "string", "description": "Only with support:content." }, "customValues": { "type": "object", "description": "Only with support:content." } }, "type": "object", "required": [ "id", "taskId", "conversationId", "title", "status", "taskStatus", "etag" ], "title": "ApiTicket", "description": "A support ticket (its task is support.ticket:, one per support conversation). The ETag is synthetic (W/\"h:…\")." }, "ApiTicketEvents": { "properties": { "ticketId": { "type": "string" }, "taskId": { "type": "string" }, "total": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "visibility": { "type": "string", "enum": [ "internal", "public" ] }, "actor": { "properties": { "kind": { "type": "string", "enum": [ "user", "system" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "at": { "type": [ "string", "null" ], "format": "date-time" }, "changedFields": { "items": { "type": "string" }, "type": "array" }, "details": { "type": "object", "description": "IDs, statuses and dates; every value only with include=body." }, "body": { "type": "string", "description": "Only with include=body (support:content)." } }, "type": "object" }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "ticketId", "items", "nextCursor", "hasMore" ], "title": "ApiTicketEvents" }, "ApiTicketFiles": { "properties": { "ticketId": { "type": "string" }, "maxFileBytes": { "type": "integer" }, "items": { "items": { "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" }, "contentType": { "type": "string" }, "visibility": { "type": "string", "enum": [ "internal", "public" ] }, "source": { "type": "string", "enum": [ "customer", "team" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" } }, "type": "object" }, "type": "array" } }, "type": "object", "required": [ "ticketId", "items" ], "title": "ApiTicketFiles" }, "ApiTicketPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiTicket" }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" }, "searchedFields": { "items": { "type": "string" }, "type": "array", "description": "search only: title and, when the source may read names, contactName (only of the contacts the source reaches: contactScope)." } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiTicketPage" }, "ApiVoiceCall": { "properties": { "id": { "type": "string" }, "conversationId": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "mode": { "type": "string", "enum": [ "assistant", "human" ] }, "status": { "type": "string" }, "dialStatus": { "type": "string" }, "durationSeconds": { "type": "integer" }, "recordingStatus": { "type": "string" }, "transcriptionStatus": { "type": "string" }, "summaryStatus": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "endedAt": { "type": [ "string", "null" ], "format": "date-time" }, "contact": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "language": { "type": "string" } }, "type": [ "object", "null" ], "description": "Only the source's read fields; only the id when the source cannot reach the contact." }, "taskIds": { "items": { "type": "string" }, "type": "array", "description": "The live tasks this record generates." }, "caller": { "type": "string", "description": "Only when the source may read phones and reaches the contact (contactScope)." }, "called": { "type": "string", "description": "Only when the source may read phones and reaches the contact (contactScope)." }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\" of the call: the If-Match of its actions." }, "summary": { "type": "string", "description": "Only with voice:content." }, "transcript": { "items": { "properties": { "speaker": { "type": "string", "enum": [ "customer", "assistant", "agent" ] }, "text": { "type": "string" } }, "type": "object" }, "type": "array", "description": "GET /api/v1/voice/calls/{call_id} only, with voice:content." }, "jobs": { "items": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "agent", "summary", "recording", "email" ] }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed", "uncertain", "cancelled" ] }, "attempts": { "type": "integer" }, "errorCode": { "type": "string", "enum": [ "", "processing_failed", "not_sent", "delivery_unconfirmed", "other" ] }, "recipient": { "type": [ "string", "null" ], "description": "Masked; only when the source may read emails and reaches the contact (contactScope)." } }, "type": "object" }, "type": "array", "description": "GET /api/v1/voice/calls/{call_id} only: the call's jobs." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "GET /api/v1/voice/calls/{call_id} only: email_summary." } }, "type": "object", "required": [ "id", "status", "taskIds", "etag" ], "title": "ApiVoiceCall", "description": "A phone call. The recording is never served: no audio URL and no audio route." }, "ApiVoiceCallPage": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ApiVoiceCall" }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiVoiceCallPage" }, "ApiVoiceCapacity": { "properties": { "limit": { "type": "integer" }, "active": { "type": "integer" }, "available": { "type": "integer" }, "uncertain": { "type": "integer" }, "canStartCall": { "type": "boolean" }, "pendingReviews": { "items": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ] }, "callId": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "hasProviderCall": { "type": "boolean" }, "reasonCode": { "type": "string", "enum": [ "", "status_unconfirmed", "provider_unconfirmed", "call_mismatch", "dispatch_uncertain", "other" ] }, "etag": { "type": "string" }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." } }, "type": "object" }, "type": "array", "description": "Calls whose status the provider did not confirm (their task is voice.capacity_review:)." }, "rejectedCount24h": { "type": "integer" }, "rejectedRecent": { "items": { "properties": { "id": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "caller": { "type": "string", "description": "Only when the source may read phones and has contactScope=company (a turned away call has no contact)." }, "called": { "type": "string", "description": "Only when the source may read phones and has contactScope=company (a turned away call has no contact)." } }, "type": "object" }, "type": "array", "description": "Inbound calls turned away at the limit in the last 24 h." } }, "type": "object", "required": [ "limit", "active", "available", "uncertain", "canStartCall", "pendingReviews" ], "title": "ApiVoiceCapacity", "description": "The company's concurrent call capacity. Never the plan or its override." }, "ApiVoiceJobPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "taskId": { "type": [ "string", "null" ], "description": "Only when the job is a task." }, "taskStatus": { "type": [ "string", "null" ], "enum": [ "in_progress", "needs_review", "done", "cancelled", null ] }, "signals": { "items": { "type": "string", "enum": [ "uncertain", "failed" ] }, "type": "array" }, "callId": { "type": "string" }, "conversationId": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "agent", "summary", "recording", "email" ] }, "status": { "type": "string", "enum": [ "pending", "running", "done", "failed", "uncertain", "cancelled" ] }, "attempts": { "type": "integer" }, "errorCode": { "type": "string", "enum": [ "", "processing_failed", "not_sent", "delivery_unconfirmed", "other" ] }, "retryable": { "type": "boolean", "description": "Failed or uncertain and not an assistant turn." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "etag": { "type": "string", "description": "W/\"h:<16 hex>\": the If-Match of retry." }, "actions": { "items": { "properties": { "name": { "type": "string" }, "scope": { "type": "string" }, "actor": { "type": "string", "enum": [ "service", "delegated", "owner", "recipient" ] }, "available": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "STATE", "DELEGATED_USER_REQUIRED", "MAILBOX_OWNER_REQUIRED", "SCOPE_MISSING", "FEATURE_DISABLED", "SEND_SWITCH_OFF", "ACTOR_ROLE_INSUFFICIENT", "MENTION_RECIPIENT_REQUIRED" ], "description": "Clients ignore values they do not know." }, "preview": { "type": "boolean", "description": "The action has a native previous step (dryRun returns its token)." }, "inputSchema": { "type": "string", "description": "Reference to the input JSON schema in GET /api/v1/task-kinds." } }, "type": "object", "required": [ "name", "scope", "actor", "available", "preview" ] }, "type": "array", "description": "The actions with their availability for this key and delegated user." }, "recipient": { "type": [ "string", "null" ], "description": "Email jobs: masked; only when the source may read emails and reaches the contact (contactScope)." } }, "type": "object", "required": [ "id", "callId", "kind", "status", "etag", "actions" ], "description": "A job of a call (summary, recording, summary email or assistant turn). Its task, while it is one, is voice.job:; assistant turns are never tasks." }, "type": "array", "description": "Newest first." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "nextCursor", "hasMore" ], "title": "ApiVoiceJobPage" }, "ApiWebFormPage": { "properties": { "items": { "items": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "origin": { "type": "string" }, "allowedPaths": { "items": { "type": "string" }, "type": "array" }, "selector": { "type": "string" }, "fields": { "items": { "type": "object" }, "type": "array" }, "mappings": { "items": { "type": "object" }, "type": "array" }, "enabled": { "type": "boolean" }, "captureMode": { "type": "string" }, "successEvent": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastSubmissionAt": { "type": [ "string", "null" ], "format": "date-time" }, "submissionCount": { "type": "integer" }, "issueCount": { "type": "integer" } }, "type": "object" }, "type": "array", "description": "Forms of the company's own websites, newest first; never their submissions nor their public key." }, "total": { "type": "integer" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor of the next page (24 h, bound to this key's source and filters); null on the last page." }, "hasMore": { "type": "boolean" } }, "type": "object", "required": [ "items", "total", "nextCursor", "hasMore" ], "title": "ApiWebFormPage" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } }, "securitySchemes": { "aioApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "aio_.", "description": "Key of an integration source, created by a company administrator in Settings > Integrations > API and events. Only its digest is stored; revoked or expired keys answer 401 at once." } } } }