{ "openapi": "3.1.0", "paths": { "/v2/me": { "get": { "description": "Returns the organization, the key and its scopes. Needs no scope. The first call of any integration.", "operationId": "me.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [] } ], "summary": "Retrieve the current key", "tags": [ "Me" ], "x-lelemon-effect": "read" } }, "/v2/scopes": { "get": { "description": "Every scope a key can carry, with what it allows. Needs no scope.", "operationId": "scopes.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [] } ], "summary": "List scopes", "tags": [ "API keys" ], "x-lelemon-effect": "read" } }, "/v2/agents": { "post": { "description": "Creates a draft agent from scratch (name, instructions and llmConfig) or from a template with fromTemplate. Anything you send overrides the template. llmConfig.model is a public id from GET /v2/models such as anthropic/claude-sonnet-4.6. Activate it when it is ready. audience internal creates a copilot for your team that can use the tools of your data connector (dct_): it needs the scope agents:internal, cannot come from a template and cannot be changed later; you operate it afterwards like any agent.\n\nRequired scope: `agents:write`.", "operationId": "agents.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgent" }, "examples": { "fromTemplate": { "summary": "fromTemplate", "value": { "fromTemplate": "atp_02y0e5MANqacVbmtn1YyeJ" } }, "custom": { "summary": "custom", "value": { "name": "Order bot", "instructions": "You answer questions about orders in one short sentence.", "llmConfig": { "model": "anthropic/claude-sonnet-5.5" }, "channels": [ "whatsapp" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Create an agent", "tags": [ "Agents" ], "x-lelemon-effect": "write", "x-required-scopes": [ "agents:write" ] }, "get": { "description": "Newest first.\n\nRequired scope: `agents:read`.", "operationId": "agents.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] } }, { "name": "slug", "required": false, "in": "query", "description": "Exact match on the agent slug.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "List agents", "tags": [ "Agents" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] } }, "/v2/agents/{id}": { "get": { "description": "Returns one agent by id. Use it to refresh a single record you already know; to find records, use the list route. To change it, use the update route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `agents:read`.", "operationId": "agents.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "Retrieve an agent", "tags": [ "Agents" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] }, "patch": { "description": "Changes only what you send. Changing instructions or variables creates a version. Send expectedVersion so two people cannot overwrite each other: if someone saved first you get 409 agent_version_conflict. llmConfig replaces the whole model configuration; send model as a public id from GET /v2/models.\n\nRequired scope: `agents:write`.", "operationId": "agents.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgent" }, "example": { "instructions": "You answer questions about orders in one short sentence.", "llmConfig": { "model": "anthropic/claude-sonnet-5.5", "temperature": 0.3 }, "expectedVersion": 3 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Update an agent", "tags": [ "Agents" ], "x-lelemon-effect": "write", "x-required-scopes": [ "agents:write" ] }, "delete": { "description": "Answers 409 resource_in_use while the agent has open conversations or serves a pipeline stage.\n\nRequired scope: `agents:write`.", "operationId": "agents.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Delete an agent", "tags": [ "Agents" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "agents:write" ] } }, "/v2/agents/{id}/activate": { "post": { "description": "Turns the agent on, so it starts answering real people, and says in readiness what still keeps people from reaching it: no stage, not the entry stage, or no api channel. An empty readiness.missing means it is reachable. Use dryRun=true first: it runs the same checks (422 agent_not_ready when something is missing) and answers with the agent as it would be once active and its readiness, without turning it on.\n\nRequired scope: `agents:write`.", "operationId": "agents.activate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string" }, "audience": { "type": "string", "enum": [ "customers", "internal" ], "description": "customers: talks to your customers. internal: a copilot for your team created with the scope agents:internal." }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "version": { "type": "integer", "description": "Goes up on every change. Send it back as expectedVersion." }, "instructions": { "type": "string", "description": "As you wrote them, with the {{name}} placeholders still in place." }, "variables": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "llmConfig": { "$ref": "#/components/schemas/ModelConfig" }, "maxTokens": { "type": "integer" }, "maxIterations": { "type": "integer" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp", "api", "web", "email" ] } }, "behaviors": { "type": "object", "additionalProperties": true }, "avatar": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readiness": { "$ref": "#/components/schemas/Readiness" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "audience", "description", "status", "version", "instructions", "variables", "llmConfig", "maxTokens", "maxIterations", "channels", "behaviors", "avatar", "createdAt", "updatedAt", "readiness" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Activate an agent", "tags": [ "Agents" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "agents:write" ] } }, "/v2/agents/{id}/pause": { "post": { "description": "Stops answering. Open conversations stay; it answers again when activated.\n\nRequired scope: `agents:write`.", "operationId": "agents.pause", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentWithReadiness" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Pause an agent", "tags": [ "Agents" ], "x-lelemon-effect": "write", "x-required-scopes": [ "agents:write" ] } }, "/v2/agents/{id}/versions": { "get": { "description": "Newest first, without the text. A version is saved each time the instructions or variables change, and says who made it.\n\nRequired scope: `agents:read`.", "operationId": "agents.versions.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersionList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "List versions", "tags": [ "Agents" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] } }, "/v2/agents/{id}/versions/{versionId}": { "get": { "description": "Includes the instructions and variables of that version.\n\nRequired scope: `agents:read`.", "operationId": "agents.versions.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "versionId", "required": true, "in": "path", "description": "The id of the agent version (agv_…).", "schema": { "type": "string", "pattern": "^agv_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentVersionWithText" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "Retrieve a version", "tags": [ "Agents" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] } }, "/v2/agents/{id}/versions/{versionId}/restore": { "post": { "description": "Writes that version's instructions and variables as a new version. History never shrinks.\n\nRequired scope: `agents:write`.", "operationId": "agents.versions.restore", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "versionId", "required": true, "in": "path", "description": "The id of the agent version (agv_…).", "schema": { "type": "string", "pattern": "^agv_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Restore a version", "tags": [ "Agents" ], "x-lelemon-effect": "write", "x-required-scopes": [ "agents:write" ] } }, "/v2/agents/{id}/facts": { "get": { "description": "The facts the agent keeps in its memory and receives in every conversation: the ones you save here and the ones it saved on its own. Most recently updated first, up to 50 in total. Add q to keep the facts whose key or value contains that text. Facts are not versioned: saving one replaces the previous value. Read only. It is safe to repeat.\n\nRequired scope: `agents:read`.", "operationId": "agents.facts.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Only the facts whose key or value contains this text.", "schema": { "maxLength": 120, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFactList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "List the fixed facts of an agent", "tags": [ "Agents" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] }, "put": { "description": "Saves the value under the key. If the agent already has a fact with that key, the value is replaced; otherwise it is added. key is snake_case. It is safe to repeat with the same body: the result does not change.\n\nRequired scope: `agents:write`.", "operationId": "agents.facts.set", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAgentFact" }, "example": { "key": "horario", "value": "Lunes a viernes de 9 a 18" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFact" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Save a fixed fact of an agent", "tags": [ "Agents" ], "x-lelemon-effect": "write", "x-required-scopes": [ "agents:write" ] } }, "/v2/agents/{id}/facts/{key}": { "delete": { "description": "The agent stops receiving that fact. Repeating the call returns 404 not_found, because the fact no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `agents:write`.", "operationId": "agents.facts.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "key", "required": true, "in": "path", "description": "The key of the fact.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Forgotten." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:write" ] } ], "summary": "Forget a fixed fact of an agent", "tags": [ "Agents" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "agents:write" ] } }, "/v2/agent-templates": { "get": { "description": "Lelemon's templates plus the ones your organization created. Use an id as fromTemplate in POST /v2/agents; variables lists what its instructions ask for.\n\nRequired scope: `agents:read`.", "operationId": "agentTemplates.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTemplateList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "List agent templates", "tags": [ "Models and templates" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] } }, "/v2/models": { "get": { "description": "Lists the models you can put in an agent's llmConfig.model. Use it before creating or updating an agent to pick a valid id; do not guess ids. Each model has a stable public id such as anthropic/claude-sonnet-4.6, the context window in tokens, whether thinking can be turned off, and deprecated, the date the model stops being accepted or null. The id does not change when Lelemon changes the provider or the region behind it. Read only and idempotent.\n\nRequired scope: `agents:read`.", "operationId": "models.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "agents:read" ] } ], "summary": "List models", "tags": [ "Models and templates" ], "x-lelemon-effect": "read", "x-required-scopes": [ "agents:read" ] } }, "/v2/subaccounts": { "post": { "description": "A subaccount is a child organization with its own agents, pipelines, cases, numbers and keys, isolated from your other subaccounts. Act on it with the Lelemon-Subaccount header on any route. fromTemplates fills it with draft agents and pipelines: agent ids come from GET /v2/agent-templates, pipeline ids from GET /v2/pipelines.\n\nRequired scope: `subaccounts:write`.", "operationId": "subaccounts.create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubaccount" }, "example": { "externalRef": "local-1042", "name": "Cafe Central", "fromTemplates": { "agents": [ "atp_02y0e5MANqacVbmtn1YyeJ" ] } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subaccount" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "subaccounts:write" ] } ], "summary": "Create a subaccount", "tags": [ "Subaccounts" ], "x-lelemon-effect": "write", "x-required-scopes": [ "subaccounts:write" ] }, "get": { "description": "Newest first. Filter by externalRef.\n\nRequired scope: `subaccounts:read`.", "operationId": "subaccounts.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "externalRef", "required": false, "in": "query", "description": "Only the subaccount with this ref.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "subaccounts:read" ] } ], "summary": "List subaccounts", "tags": [ "Subaccounts" ], "x-lelemon-effect": "read", "x-required-scopes": [ "subaccounts:read" ] } }, "/v2/subaccounts/{id}": { "get": { "description": "Returns one subaccount by id. Use it to refresh a single record you already know; to find records, use the list route. Only a platform key can read its subaccounts. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `subaccounts:read`.", "operationId": "subaccounts.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the subaccount (sub_…).", "schema": { "type": "string", "pattern": "^sub_[0-9A-Za-z]{22}$" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subaccount" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "subaccounts:read" ] } ], "summary": "Retrieve a subaccount", "tags": [ "Subaccounts" ], "x-lelemon-effect": "read", "x-required-scopes": [ "subaccounts:read" ] }, "patch": { "description": "Changes the name or the external reference of a subaccount. Send only the fields you want to change. It does not touch the subaccount keys or the resources it holds. Applying the same body twice leaves the same result.\n\nRequired scope: `subaccounts:write`.", "operationId": "subaccounts.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the subaccount (sub_…).", "schema": { "type": "string", "pattern": "^sub_[0-9A-Za-z]{22}$" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubaccount" }, "example": { "name": "Cafe Central Centro" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subaccount" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "subaccounts:write" ] } ], "summary": "Update a subaccount", "tags": [ "Subaccounts" ], "x-lelemon-effect": "write", "x-required-scopes": [ "subaccounts:write" ] }, "delete": { "description": "Revokes its keys and closes it. It must have no WhatsApp numbers and no pending connection: disconnect them first.\n\nRequired scope: `subaccounts:write`.", "operationId": "subaccounts.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the subaccount (sub_…).", "schema": { "type": "string", "pattern": "^sub_[0-9A-Za-z]{22}$" } } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "subaccounts:write" ] } ], "summary": "Delete a subaccount", "tags": [ "Subaccounts" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "subaccounts:write" ] } }, "/v2/subaccounts/{id}/api-keys": { "post": { "description": "For direct access: a key that only sees this subaccount. Its scopes cannot go beyond yours, and the key is shown once. This route ignores Idempotency-Key so the secret is never stored.\n\nRequired scope: `subaccounts:write`.", "operationId": "subaccounts.apiKeys.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the subaccount (sub_…).", "schema": { "type": "string", "pattern": "^sub_[0-9A-Za-z]{22}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubaccountKey" }, "example": { "name": "Cafe Central POS", "scopes": [ "cases:read", "cases:write" ], "expiresInDays": 90 } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountKey" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "subaccounts:write" ] } ], "summary": "Give a subaccount its own key", "tags": [ "Subaccounts" ], "x-lelemon-effect": "write", "x-required-scopes": [ "subaccounts:write" ], "x-lelemon-returns-secret": true } }, "/v2/whatsapp/connections": { "post": { "description": "Returns a setupUrl for the account owner to link their WhatsApp number. Only the number in phone can be linked: any other one ends the connection as failed and is not attached. When the number is linked, it answers with agentId and the phone_number.connected event is sent. One pending link per account.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.connections.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWhatsappConnection" }, "example": { "phone": "+56912345678", "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "connectionType": "coexistence", "redirects": { "success": "https://app.example.com/whatsapp/connected", "failure": "https://app.example.com/whatsapp/failed" }, "language": "es" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConnection" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Create a WhatsApp connection link", "tags": [ "WhatsApp" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] }, "get": { "description": "Newest first.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.connections.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "connected", "failed", "revoked", "expired", "disconnected" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConnectionList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "List WhatsApp connections", "tags": [ "WhatsApp" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/whatsapp/connections/{id}": { "get": { "description": "Returns one WhatsApp connection by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.connections.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the whatsapp connection (wcn_…).", "schema": { "type": "string", "pattern": "^wcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappConnection" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Retrieve a WhatsApp connection", "tags": [ "WhatsApp" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] }, "delete": { "description": "Kills the setupUrl. Only a pending connection can be revoked; to remove a linked number use DELETE /v2/whatsapp/phone-numbers/{id}.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.connections.revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the whatsapp connection (wcn_…).", "schema": { "type": "string", "pattern": "^wcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Revoke a pending WhatsApp connection", "tags": [ "WhatsApp" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/whatsapp/phone-numbers": { "get": { "description": "Newest first.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.phoneNumbers.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumberList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "List WhatsApp phone numbers", "tags": [ "WhatsApp" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/whatsapp/phone-numbers/{id}": { "get": { "description": "Returns one WhatsApp phone number by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.phoneNumbers.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the phone number (pn_…).", "schema": { "type": "string", "pattern": "^pn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Retrieve a WhatsApp phone number", "tags": [ "WhatsApp" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] }, "patch": { "description": "Use it to switch the agent that answers (agentId), stop answering without disconnecting (active: false) or name the number, for example by branch (label, null clears it). Only the fields you send change, and the call is idempotent. It does not set business hours or a time zone: those belong to the organization, not to a number, and a field this route does not know is not applied.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.phoneNumbers.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the phone number (pn_…).", "schema": { "type": "string", "pattern": "^pn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePhoneNumber" }, "example": { "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "active": true, "label": "Sucursal Centro", "catalogId": "1234567890" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneNumber" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Change the agent, label or state of a number", "tags": [ "WhatsApp" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] }, "delete": { "description": "Detaches the number from the provider and stops its agent. The phone_number.disconnected event is sent.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.phoneNumbers.disconnect", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the phone number (pn_…).", "schema": { "type": "string", "pattern": "^pn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Disconnect a WhatsApp phone number", "tags": [ "WhatsApp" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/whatsapp/phone-numbers/{id}/commerce-settings": { "get": { "description": "Use it before sending product, product_list or catalog messages to know whether the cart button (isCartEnabled) and the catalog icon (isCatalogVisible) are on, and which catalog the number has (catalogId). Read only and safe to repeat. It asks WhatsApp through the provider, so it answers 503 service_unavailable when the provider does not answer. 404 not_found when the id does not exist or belongs to another organization.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.phoneNumbers.commerceSettings.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the phone number (pn_…).", "schema": { "type": "string", "pattern": "^pn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceSettings" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Read the cart and catalog settings of a number", "tags": [ "WhatsApp" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] }, "patch": { "description": "Use it to show or hide the cart button (isCartEnabled) and the catalog icon in the chat (isCatalogVisible) of one number. Only the fields you send change, and the call is idempotent. It does not connect a catalog: the catalog is created in Meta Commerce Manager and connected in WhatsApp Manager, then you save its id with PATCH /v2/whatsapp/phone-numbers/{id} (catalogId). It writes to WhatsApp through the provider, so it answers 503 service_unavailable when the provider does not accept it.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.phoneNumbers.commerceSettings.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the phone number (pn_…).", "schema": { "type": "string", "pattern": "^pn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommerceSettings" }, "example": { "isCartEnabled": true, "isCatalogVisible": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommerceSettings" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Turn the cart button or the catalog icon of a number on or off", "tags": [ "WhatsApp" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/actions": { "post": { "description": "Registers an HTTP endpoint of yours that agents can call. The URL must be public and its site must be allowed for this key (an administrator adds sites to the key). Credentials go in request.headers: they are stored encrypted and never returned. Nothing can use the action until you grant it to an agent with PUT /v2/agents/{id}/tools/{toolId}. The URL is called exactly as written: a placeholder such as {id} is rejected with 400 (param request.url); what the agent must fill goes in input (query for GET, body otherwise). Optional authorization block records the purpose and where the system is hosted (Law 21.719): read the text with GET /v2/actions/authorization. Use dryRun=true to run the same checks (name, site allowed for the key, destination, input, authorization) and get 200 with the action as it would be saved, without saving it; its id is not saved.\n\nRequired scope: `actions:write`.", "operationId": "actions.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAction" }, "example": { "name": "create_order", "description": "Create an order when the customer confirms what they want to buy.", "request": { "method": "POST", "url": "https://api.mesa.cl/lelemon/orders", "headers": { "Authorization": "Bearer your-secret" }, "timeoutMs": 10000 }, "input": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "string" } } } }, "audience": "customers" } } } }, "responses": { "200": { "description": "dryRun=true: the action as it would be saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action" ] }, "id": { "type": "string", "example": "act_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string", "example": "create_order" }, "description": { "type": "string" }, "request": { "$ref": "#/components/schemas/ActionRequest" }, "input": { "type": "object", "additionalProperties": true }, "audience": { "type": "string", "enum": [ "all", "customers", "internal" ] }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, every subaccount of yours can grant this action to its own agents. The action keeps living in your organization: calls to it are signed with your signing secret and carry the Lelemon-Subaccount-Id of the subaccount that made the call. Subaccounts cannot read, change or delete it. Turning it off, or deleting the action, removes it from the agents of your subaccounts. Its name cannot match an action that one of your subaccounts already has." }, "variables": { "description": "The fields Lelemon fills on every call. Empty when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/ActionVariable" } }, "authorization": { "description": "The authorization in force for the destination of this action: what you accepted when you created it or last changed its destination. null when there is none, for example after the destination changed and was not authorized again, and always null on an action shared by your platform.", "anyOf": [ { "$ref": "#/components/schemas/ActionAuthorizationRecord" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "description", "request", "input", "audience", "noPersist", "sharedWithSubaccounts", "variables", "authorization", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Create an action", "tags": [ "Actions" ], "x-lelemon-effect": "write", "x-required-scopes": [ "actions:write" ] }, "get": { "description": "The actions you registered, newest first. It does not include Lelemon tools or MCP tools: see GET /v2/agents/{id}/tools for what an agent can use.\n\nRequired scope: `actions:read`.", "operationId": "actions.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "List actions", "tags": [ "Actions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] } }, "/v2/actions/authorization": { "get": { "description": "The text you accept when an action sends personal data to your system (article 15 bis of Law 21.719), its version and the extra confirmation for a system outside Chile. Read it before sending authorization in POST /v2/actions or PATCH /v2/actions/{id}; when the text changes, the version changes and old versions are refused. Read only.\n\nRequired scope: `actions:read`.", "operationId": "actions.authorization.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionAuthorization" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "Read the current authorization text", "tags": [ "Actions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] } }, "/v2/actions/signing-secret/rotate": { "post": { "description": "Every call of an action to your system carries a Lelemon-Signature header and the turn context (case, contact, subaccount, actor). The secret behind it belongs to your organization and each action gets its own, derived from it. This creates a new one: the previous keeps signing alongside the new one for 24 hours, so you can change the secrets in your systems without a cut. Every call rotates again, and the secret of the earlier rotation stops being listed: send an Idempotency-Key so a retry does not rotate twice. The response does not carry any secret: read each one with GET /v2/actions/{id}/signing-secret. Use dryRun=true to see when the previous secret would stop working; nothing rotates.\n\nRequired scope: `actions:write`.", "operationId": "actions.rotateSigningSecret", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action_signing_secret_rotation" ] }, "rotatedAt": { "type": "string", "format": "date-time" }, "previousValidUntil": { "type": "string", "format": "date-time", "description": "Until when calls signed with the previous secret still verify. Read the new secret of each action with GET /v2/actions/{id}/signing-secret." }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "rotatedAt", "previousValidUntil" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Rotate the signing secret of your actions", "tags": [ "Actions" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "actions:write" ] } }, "/v2/actions/{id}/signing-secret": { "get": { "description": "Use it to verify that a call to your system comes from Lelemon: pass the whole secrets list, the raw body and the full URL to verifyRequest of the SDK. It needs actions:write because it is a secret. Read only; calling it again returns the same secrets until you rotate. The Test an action endpoint does not sign: only calls made in a turn do.\n\nRequired scope: `actions:write`.", "operationId": "actions.retrieveSigningSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionSigningSecret" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Retrieve the signing secret of an action", "tags": [ "Actions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:write" ], "x-lelemon-returns-secret": true } }, "/v2/actions/{id}": { "get": { "description": "Returns one action by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `actions:read`.", "operationId": "actions.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "Retrieve an action", "tags": [ "Actions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] }, "patch": { "description": "Changes only what you send. request is merged field by field; input replaces the whole schema. The name cannot change. Use dryRun=true to run the same checks and get the action as it would be saved, without saving it.\n\nRequired scope: `actions:write`.", "operationId": "actions.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAction" }, "example": { "description": "Create an order once the customer confirms the items.", "request": { "timeoutMs": 15000 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action" ] }, "id": { "type": "string", "example": "act_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string", "example": "create_order" }, "description": { "type": "string" }, "request": { "$ref": "#/components/schemas/ActionRequest" }, "input": { "type": "object", "additionalProperties": true }, "audience": { "type": "string", "enum": [ "all", "customers", "internal" ] }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, every subaccount of yours can grant this action to its own agents. The action keeps living in your organization: calls to it are signed with your signing secret and carry the Lelemon-Subaccount-Id of the subaccount that made the call. Subaccounts cannot read, change or delete it. Turning it off, or deleting the action, removes it from the agents of your subaccounts. Its name cannot match an action that one of your subaccounts already has." }, "variables": { "description": "The fields Lelemon fills on every call. Empty when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/ActionVariable" } }, "authorization": { "description": "The authorization in force for the destination of this action: what you accepted when you created it or last changed its destination. null when there is none, for example after the destination changed and was not authorized again, and always null on an action shared by your platform.", "anyOf": [ { "$ref": "#/components/schemas/ActionAuthorizationRecord" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "description", "request", "input", "audience", "noPersist", "sharedWithSubaccounts", "variables", "authorization", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Update an action", "tags": [ "Actions" ], "x-lelemon-effect": "write", "x-required-scopes": [ "actions:write" ] }, "delete": { "description": "Also removes it from every agent that had it. The name stays reserved: creating an action with the same name again brings this one back with what you send.\n\nRequired scope: `actions:write`.", "operationId": "actions.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Delete an action", "tags": [ "Actions" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "actions:write" ] } }, "/v2/actions/{id}/test": { "post": { "description": "Calls your endpoint once with the sample input, the way an agent would, but without an agent. The answer is the status and the body your endpoint returned, cut at 4000 characters and with your credential hidden. A refused destination is a 400; an endpoint that does not answer is a 200 with ok false. At most 10 tests per minute per organization. Note that it really calls your endpoint: use sample data when the action writes.\n\nRequired scope: `actions:write`.", "operationId": "actions.test", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestAction" }, "example": { "input": { "items": [ "2 coffees" ] } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionTest" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Test an action", "tags": [ "Actions" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "actions:write" ] } }, "/v2/mcp-servers": { "post": { "description": "Connects a Streamable HTTP MCP server and asks it for its tools right away. The URL must be public and its site must be allowed for this key, the same list actions use. The connection is made to the address that was checked and redirects are not followed, so a server that redirects to an internal address is rejected. If the server does not answer, nothing is saved and the answer is 422 mcp_server_unreachable. Grant its tools to agents with PUT /v2/agents/{id}/tools/{toolId}.\n\nRequired scope: `actions:write`.", "operationId": "mcpServers.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectMcpServer" }, "example": { "name": "Mesa menu", "url": "https://mcp.mesa.cl", "auth": { "type": "bearer", "token": "your-secret" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerWithTools" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Connect an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "write", "x-required-scopes": [ "actions:write" ] }, "get": { "description": "Newest first, without their tools.\n\nRequired scope: `actions:read`.", "operationId": "mcpServers.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "List MCP servers", "tags": [ "MCP servers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] } }, "/v2/mcp-servers/{id}": { "get": { "description": "Includes the tools found by the last discovery.\n\nRequired scope: `actions:read`.", "operationId": "mcpServers.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerWithTools" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "Retrieve an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] }, "patch": { "description": "Changes only what you send. A new url or auth discovers the tools again; if that fails the server stays with status error. Servers connected by OAuth are reconnected from the dashboard.\n\nRequired scope: `actions:write`.", "operationId": "mcpServers.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMcpServer" }, "example": { "name": "Mesa menu and stock" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerWithTools" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Update an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "write", "x-required-scopes": [ "actions:write" ] }, "delete": { "description": "Removes its tools from every agent that had them, then disconnects the server.\n\nRequired scope: `actions:write`.", "operationId": "mcpServers.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Disconnected." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Disconnect an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "actions:write" ] } }, "/v2/mcp-servers/{id}/tools": { "get": { "description": "The tools found by the last discovery, as a list. Use it to get the id that PUT /v2/agents/{id}/tools/{toolId} takes. It reads what is stored and does not call the server: to refresh it, call POST /v2/mcp-servers/{id}/discover.\n\nRequired scope: `actions:read`.", "operationId": "mcpServers.tools.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpToolList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "List the tools of an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] } }, "/v2/mcp-servers/{id}/discover": { "post": { "description": "Asks the server for its tools now and returns the server (not a list) with its tools in the tools field; use GET /v2/mcp-servers/{id}/tools for a paginated list. It calls the server, so it is not free to repeat: an organization can discover at most 20 times per minute, and the next call answers 429 rate_limited with Retry-After. It is safe to retry. Answers 422 mcp_server_unreachable when the server does not answer (the server is marked error until a discovery works).\n\nRequired scope: `actions:write`.", "operationId": "mcpServers.discover", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpServerWithTools" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Discover tools", "tags": [ "MCP servers" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "actions:write" ] } }, "/v2/mcp-servers/{id}/run-identity": { "get": { "description": "Use it to know whether Lelemon signs its calls to this server and with which header, audience and secret id (`kid`). It never returns the secret. When enabled is false the calls go unsigned and your server gets no verified user or case context.\n\nRequired scope: `actions:read`.", "operationId": "mcpServers.runIdentity.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRunIdentity" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "Read the run identity of an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] }, "post": { "description": "Use it so your MCP server can trust who is asking: from now on every tools/call carries a JWT (HS256, 60 seconds) in the header, with the user, case, contact and tool in its claims; verify it with the SDK (`verifyMcpAssertion`). If the identity is already on, it issues a new secret and the previous one keeps verifying until the next rotation, so accept both by `kid`. The secret is shown once, in this answer. It changes how the server is called, so it is not idempotent and ignores Idempotency-Key. Use dryRun=true to check the header and audience and see whether it would rotate; nothing is saved.\n\nRequired scope: `actions:write`.", "operationId": "mcpServers.runIdentity.activate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateMcpRunIdentity" }, "example": { "header": "x-agente-corrida", "audience": "https://mcp.mesa.cl/mcp" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mcp_run_identity" ] }, "serverId": { "type": "string", "example": "mcp_02y0e5MANqacVbmtn1YyeJ" }, "enabled": { "type": "boolean", "description": "True when Lelemon signs every call it makes to this server. False means calls go unsigned and the server gets no verified context." }, "header": { "type": "string", "example": "x-agente-corrida" }, "audience": { "type": "string", "example": "https://mcp.mesa.cl/mcp" }, "kid": { "type": [ "string", "null" ], "description": "The `kid` of the secret that signs now. The JWT header carries it, so your server picks the right secret during a rotation." }, "secretCreatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string", "description": "HS256 secret. Shown only in the answer that creates it, never again, and absent in a dryRun. Store it now." }, "rotated": { "type": "boolean", "description": "Only in the answer to POST: true when the identity was already on and this call replaced the signing secret. The previous secret keeps verifying until the next rotation, so your server accepts both for a while." }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "serverId", "enabled", "header", "audience", "kid", "secretCreatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Turn on or rotate the run identity of an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "actions:write" ], "x-lelemon-returns-secret": true }, "delete": { "description": "Lelemon stops signing its calls and forgets the secrets. Do it only after your server stops requiring the JWT, or its calls will be rejected. Safe to repeat.\n\nRequired scope: `actions:write`.", "operationId": "mcpServers.runIdentity.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the mcp server (mcp_…).", "schema": { "type": "string", "pattern": "^mcp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Turned off." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Turn off the run identity of an MCP server", "tags": [ "MCP servers" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "actions:write" ] } }, "/v2/data-connectors/format": { "get": { "description": "Returns the JSON Schemas of the four documents your connector serves (manifest, account card, account search and view page) and their limits. Use it to build or validate your connector before registering it. It reads nothing of your data and is safe to repeat.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.format.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorFormat" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Get the lelemon-connector/v1 format", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/format/validate": { "post": { "description": "Use it while you build your connector, before you register it: send the manifest, an account card, an account search answer or a view page exactly as you serve them, and get every place that does not follow lelemon-connector/v1 with its path (such as $.sections[0].components[1].value) and the reason, never the value. It runs the same validator that checks the real answers of your system, so a document that passes here passes there. Nothing is stored and nothing is sent to your system, so it is safe to repeat. For an account card send baseUrl or allowedOrigins, or its action links are rejected. To check the manifest your registered system serves, use POST /v2/data-connectors/{id}/check.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.format.validate", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateConnectorDocument" }, "example": { "type": "account", "baseUrl": "https://admin.example.com/lelemon", "document": { "object": "account", "id": "acc_1", "title": "Acme", "sections": [] } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorFormatValidation" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Validate a connector document", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors": { "post": { "description": "Registers the API of your system that serves lelemon-connector/v1: account cards and views that Lelemon reads live and never stores. The base URL must be https, public, and its site must be allowed for this key: an http URL, one with a user or password, or a private address answers 422 action_destination_blocked. It does not call your system: read the signing secret with GET /v2/data-connectors/{id}/signing-secret, serve the format, then call POST /v2/data-connectors/{id}/check. Until the check passes the connector is pending and gives no tools to the copilot.\n\nRequired scope: `connectors:write`.", "operationId": "dataConnectors.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataConnector" }, "example": { "name": "Backoffice", "baseUrl": "https://admin.example.com/lelemon", "allowedOrigins": [ "https://admin.example.com" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnector" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:write" ] } ], "summary": "Register a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "write", "x-required-scopes": [ "connectors:write" ] }, "get": { "description": "Newest first. It does not call your systems.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "List data connectors", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/{id}": { "get": { "description": "Its status and the origin of its base URL. It does not call your system.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnector" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Retrieve a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:read" ] }, "patch": { "description": "Changes only what you send. A new baseUrl or new allowedOrigins put the connector back to pending and drop its stored manifest until you call the check endpoint again. The sites must be allowed for this key.\n\nRequired scope: `connectors:write`.", "operationId": "dataConnectors.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDataConnector" }, "example": { "name": "Backoffice Chile" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnector" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:write" ] } ], "summary": "Update a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "write", "x-required-scopes": [ "connectors:write" ] }, "delete": { "description": "Stops every read through it and removes its tools from the copilot. The audit of past reads is kept for two years.\n\nRequired scope: `connectors:write`.", "operationId": "dataConnectors.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:write" ] } ], "summary": "Delete a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "connectors:write" ] } }, "/v2/data-connectors/{id}/signing-secret": { "get": { "description": "Every call of Lelemon to your connector carries a Lelemon-Signature header. Pass the whole secrets list, the method, the full URL and the raw body (empty) to verifyRequest of the SDK with domain connector. The signature covers the path and query, so it is worthless for any other route, and it expires in 60 seconds. It needs connectors:write because it is a secret. Read only: it returns the same secrets until you rotate.\n\nRequired scope: `connectors:write`.", "operationId": "dataConnectors.retrieveSigningSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorSigningSecret" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:write" ] } ], "summary": "Retrieve the signing secret of a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:write" ], "x-lelemon-returns-secret": true } }, "/v2/data-connectors/{id}/signing-secret/rotate": { "post": { "description": "Creates a new secret. The previous one keeps signing alongside the new one for 24 hours, so you can change it in your system without a cut. Every call rotates again, and the secret of the earlier rotation stops being listed: send an Idempotency-Key so a retry does not rotate twice. The response carries no secret: read it with GET /v2/data-connectors/{id}/signing-secret. Use dryRun=true to see when the previous secret would stop working; nothing rotates.\n\nRequired scope: `connectors:write`.", "operationId": "dataConnectors.rotateSigningSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_signing_secret_rotation" ] }, "rotatedAt": { "type": "string", "format": "date-time" }, "previousValidUntil": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "rotatedAt", "previousValidUntil" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:write" ] } ], "summary": "Rotate the signing secret of a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "connectors:write" ] } }, "/v2/data-connectors/{id}/check": { "post": { "description": "Calls GET {baseUrl}/manifest signed, validates it against lelemon-connector/v1 and stores the manifest. If it passes, the connector becomes active and its views become tools for the copilot. If the response does not follow the format, it answers 200 with ok false and the failing paths (never the values). It reads the manifest only: account cards, searches and views are validated when they are read, and a read that fails answers 422 data_connector_invalid_response with its failing paths; test them before with POST /v2/data-connectors/format/validate. If the connector does not answer, it answers 422 data_connector_unavailable and the connector goes to error. It calls your system and is safe to repeat, up to 20 checks per minute for an organization: the next one answers 429 rate_limited with Retry-After.\n\nRequired scope: `connectors:write`.", "operationId": "dataConnectors.check", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorCheck" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:write" ] } ], "summary": "Check a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "connectors:write" ] } }, "/v2/data-connectors/{id}/manifest": { "get": { "description": "The manifest stored by the last check: its views and how accounts are looked up. It does not call your system; use it to know which views and filters exist before reading one.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.retrieveManifest", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorManifest" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Retrieve the manifest of a data connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/{id}/accounts": { "get": { "description": "Asks your connector live for the accounts whose email matches. Use it to get the stable account id; the email is only for searching, store the id as the externalRef of the contact. Titles come back masked when they look like a RUT, email or phone. Nothing is stored, only the audit of who looked. Use GET /v2/data-connectors/{id}/accounts/{account} when you already have the id.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.accounts.search", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "email", "required": true, "in": "query", "schema": { "maxLength": 320, "example": "ana@example.com", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSummaryList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Search accounts by email", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-lelemon-open-world": true, "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/{id}/accounts/{account}": { "get": { "description": "Asks your connector for the card of one account and returns it masked: fields marked sensitive and any value shaped like a RUT, email or phone come back with value null and masked true. Nothing is stored; the read is audited. To see one masked value use POST /v2/data-connectors/{id}/accounts/{account}/reveal. Answers 404 when your connector does not know the account.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.accounts.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "account", "required": true, "in": "path", "description": "The id of the account in your system, exactly as the connector returns it from the search.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountCard" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Read the card of an account live", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-lelemon-open-world": true, "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/{id}/accounts/{account}/reveal": { "post": { "description": "Reads the card live again and returns the real value of one field. The audit records the key, the account (as a keyed hash) and the field, never the value, and it is written before the value is returned. Fields marked specialCategory cannot be revealed (403). The response is never stored for idempotent replay. Use it only when the person must see the value.\n\nRequired scope: `connectors:reveal`.", "operationId": "dataConnectors.accounts.reveal", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "account", "required": true, "in": "path", "description": "The id of the account in your system, exactly as the connector returns it from the search.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealField" }, "example": { "fieldKey": "tax_id" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealedField" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:reveal" ] } ], "summary": "Reveal one masked value of an account", "tags": [ "Data connectors" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "connectors:reveal" ] } }, "/v2/data-connectors/{id}/accounts/{account}/actions/{action}/open": { "post": { "description": "Reads the card live and returns the https link of one action, only if its host is inside the sites of the connector. Lelemon never calls the link: the person opens it in a new tab with rel=noopener noreferrer. The click is audited. The link may carry a one-time token, so the response is never stored for idempotent replay.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.accounts.openAction", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "account", "required": true, "in": "path", "description": "The id of the account in your system, exactly as the connector returns it from the search.", "schema": { "type": "string" } }, { "name": "action", "required": true, "in": "path", "description": "The name of the action, as listed by the manifest of the connector.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionLink" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Get the link of an account action", "tags": [ "Data connectors" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/{id}/views/{view}": { "get": { "description": "Asks your connector for one page of a view declared in its manifest, for example the accounts in trial. Filters go as filter[name]=value and only the names the manifest declares are accepted (422 otherwise). The page keeps the connector order and cursor; sensitive columns and values shaped like a RUT, email or phone come back masked. Nothing is stored; the read is audited.\n\nRequired scope: `connectors:read`.", "operationId": "dataConnectors.views.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "view", "required": true, "in": "path", "description": "The name of the view, as listed by the manifest of the connector.", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "filter", "required": false, "in": "query", "style": "deepObject", "explode": true, "schema": { "type": "object", "additionalProperties": { "type": "string" } } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ViewPage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:read" ] } ], "summary": "Read a view live", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:read" ] } }, "/v2/data-connectors/{id}/accesses": { "get": { "description": "Newest first. Each access has the key or member, the kind (read_account, read_view, reveal, open_action...), the view, the field and an account hash; it never has a value. integrity is tampered when a row no longer matches its signature. Kept for two years. Filter by accountId to answer a data subject request.\n\nRequired scope: `connectors:audit-read`.", "operationId": "dataConnectors.accesses.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the data connector (dcn_…).", "schema": { "type": "string", "pattern": "^dcn_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Only the accesses to this account id.", "schema": { "type": "string" } }, { "name": "kind", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "read_manifest", "read_account", "search_accounts", "read_view", "reveal", "open_action" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataConnectorAccessList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "connectors:audit-read" ] } ], "summary": "List who looked at what through a connector", "tags": [ "Data connectors" ], "x-lelemon-effect": "read", "x-required-scopes": [ "connectors:audit-read" ] } }, "/v2/agents/{id}/skills": { "post": { "description": "Writes know-how the agent loads only when the conversation needs it. In the prompt travels only the name and the description; the content is loaded by the agent when it is about to do that task, with a loading tool the agent receives on its own as soon as it has at least one skill. You do not grant it and it does not appear in the agent tools. An agent holds up to 30 skills.\n\nRequired scope: `skills:write`.", "operationId": "agents.skills.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSkill" }, "example": { "name": "Late order", "description": "Load it when a customer says an order arrived late.", "content": "# Late order\n\nApologize once, check the delivery with the order action and offer the refund policy.", "slug": "late-order" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillWithContent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "skills:write" ] } ], "summary": "Create a skill", "tags": [ "Skills" ], "x-lelemon-effect": "write", "x-required-scopes": [ "skills:write" ] }, "get": { "description": "Newest first, without the content.\n\nRequired scope: `skills:read`.", "operationId": "agents.skills.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "skills:read" ] } ], "summary": "List skills", "tags": [ "Skills" ], "x-lelemon-effect": "read", "x-required-scopes": [ "skills:read" ] } }, "/v2/agents/{id}/skills/{skillId}": { "get": { "description": "Includes the content.\n\nRequired scope: `skills:read`.", "operationId": "agents.skills.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "skillId", "required": true, "in": "path", "description": "The id of the skill (skl_…).", "schema": { "type": "string", "pattern": "^skl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillWithContent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "skills:read" ] } ], "summary": "Retrieve a skill", "tags": [ "Skills" ], "x-lelemon-effect": "read", "x-required-scopes": [ "skills:read" ] }, "patch": { "description": "Changes only what you send. The slug cannot change. The change reaches every agent that has this skill.\n\nRequired scope: `skills:write`.", "operationId": "agents.skills.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "skillId", "required": true, "in": "path", "description": "The id of the skill (skl_…).", "schema": { "type": "string", "pattern": "^skl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSkill" }, "example": { "description": "Load it when a customer complains about a late delivery." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkillWithContent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "skills:write" ] } ], "summary": "Update a skill", "tags": [ "Skills" ], "x-lelemon-effect": "write", "x-required-scopes": [ "skills:write" ] }, "delete": { "description": "Deletes the skill from your organization and removes it from every agent that had it, not only this one. Answers 409 while another skill requires it.\n\nRequired scope: `skills:write`.", "operationId": "agents.skills.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "skillId", "required": true, "in": "path", "description": "The id of the skill (skl_…).", "schema": { "type": "string", "pattern": "^skl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "skills:write" ] } ], "summary": "Delete a skill", "tags": [ "Skills" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "skills:write" ] } }, "/v2/agents/{id}/tools": { "get": { "description": "Every action and MCP tool this agent could use, plus the Lelemon system tools (transfer_to_human, save_case_data, send_buttons, send_list, send_products, send_carousel, send_cta_url, send_flow, request_location, ask_team, check_availability, schedule_meeting and cancel_meeting), with granted saying which ones it may use now. Newest first, system tools last. For a granted transfer_to_human or save_case_data, config holds how it was set up; the other system tools take no config. Other Lelemon built-in tools and connectors are not listed here.\n\nRequired scope: `actions:read`.", "operationId": "agents.tools.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "granted", "required": false, "in": "query", "description": "true: only what the agent may use. false: only what it could use but has not been granted.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentToolList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "List an agent's tools", "tags": [ "Agent tools" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] } }, "/v2/agents/{id}/tools/{toolId}": { "put": { "description": "Lets the agent use an action (act_), an MCP tool (mtl_) or a system tool. Use it to give the agent the ability to hand a case to a person (path value transfer_to_human), to write the case fields whose source is agent (path value save_case_data), or to send interactive WhatsApp messages (path value send_buttons for up to 3 reply buttons, send_list for a menu of 4 to 10 options, send_products for catalog products, send_carousel for 2 to 10 swipeable cards, send_cta_url for one link button, send_flow to open a WhatsApp Flow, request_location to ask for a shared location). To let the agent book and cancel meetings on your default agenda, grant check_availability, schedule_meeting and cancel_meeting (they take no config, and the agenda has to be set up first). One tool at a time, so two people granting at once do not undo each other. Idempotent: granting twice with the same body changes nothing. For a system tool, config replaces the stored one and leaving it out clears it; transfer_to_human takes stageId, businessHours and farewell, save_case_data takes fields. For an action or MCP tool, approval puts it behind a person (see GET /v2/approvals): leaving it out keeps the current policy, mode never lifts it. To let the agent ask your team without handing over the case, grant ask_team (answers go through POST /v2/team-questions/{id}/answer). A handed-over case fires case.escalated and moves to human control.\n\nRequired scope: `actions:write`.", "operationId": "agents.tools.grant", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "toolId", "required": true, "in": "path", "description": "An action (act_…), an MCP tool (mtl_…), a data connector tool (dct_…) or a system tool name such as transfer_to_human.", "schema": { "type": "string", "pattern": "^(?:act_[0-9A-Za-z]{22}|mtl_[0-9A-Za-z]{22}|dct_[0-9A-Za-z]{22}|transfer_to_human|save_case_data|send_buttons|send_list|send_products|send_carousel|send_cta_url|send_flow|request_location|ask_team|check_availability|schedule_meeting|cancel_meeting)$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GrantTool" }, "examples": { "withApproval": { "summary": "withApproval", "value": { "approval": { "mode": "when", "condition": { "param": "amount", "op": "gt", "value": 20000 }, "approvers": [ { "type": "role", "value": "admin" } ], "expiresInMinutes": 60 } } }, "systemTool": { "summary": "systemTool", "value": { "config": { "businessHours": { "timezone": "America/Santiago", "startHour": 9, "endHour": 19, "activeSaturday": false, "activeSunday": false }, "farewell": { "duringBusinessHours": "A person from the team will write to you now.", "outsideBusinessHours": "A person from the team will write to you tomorrow morning." } } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentTool" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Grant a tool", "tags": [ "Agent tools" ], "x-lelemon-effect": "write", "x-required-scopes": [ "actions:write" ] }, "delete": { "description": "The agent stops using it. The action or MCP tool itself stays; for a system tool its configuration is deleted. Removing a tool the agent did not have is not an error.\n\nRequired scope: `actions:write`.", "operationId": "agents.tools.revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "toolId", "required": true, "in": "path", "description": "An action (act_…), an MCP tool (mtl_…), a data connector tool (dct_…) or a system tool name such as transfer_to_human.", "schema": { "type": "string", "pattern": "^(?:act_[0-9A-Za-z]{22}|mtl_[0-9A-Za-z]{22}|dct_[0-9A-Za-z]{22}|transfer_to_human|save_case_data|send_buttons|send_list|send_products|send_carousel|send_cta_url|send_flow|request_location|ask_team|check_availability|schedule_meeting|cancel_meeting)$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Removed." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Remove a tool", "tags": [ "Agent tools" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "actions:write" ] } }, "/v2/approvals": { "get": { "description": "Requests an agent made to run an action that its tool policy puts behind a person: refunds, credits, writes. Newest first. Filter by status=pending to build a queue of what waits for a decision. Read only and safe to repeat. To change what needs approval, grant the tool with an approval policy: PUT /v2/agents/{id}/tools/{toolId}.\n\nRequired scope: `approvals:read`.", "operationId": "approvals.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] } }, { "name": "agentId", "required": false, "in": "query", "schema": { "example": "agt_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "name": "caseId", "required": false, "in": "query", "schema": { "example": "cse_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:read" ] } ], "summary": "List approvals", "tags": [ "Approvals" ], "x-lelemon-effect": "read", "x-required-scopes": [ "approvals:read" ] } }, "/v2/approvals/{id}": { "get": { "description": "The exact arguments the action will run with, why it needed approval, who may decide it, who decided and why, and what the action returned. Use it before deciding, and to answer a claim afterwards. Read only and safe to repeat.\n\nRequired scope: `approvals:read`.", "operationId": "approvals.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the approval (apr_…).", "schema": { "type": "string", "pattern": "^apr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:read" ] } ], "summary": "Retrieve an approval", "tags": [ "Approvals" ], "x-lelemon-effect": "read", "x-required-scopes": [ "approvals:read" ] } }, "/v2/approvals/{id}/approve": { "post": { "description": "Approves the request and runs the action now, with the arguments you read in the approval; then the agent resumes the conversation with the result. This has the real effect of the action: it can move money or write to a person. It works only if the tool policy names this key as approver, the key has the approvals:write scope and the request was not created by this same key. Not idempotent: a request is decided once, and a second decision answers 409 approval_not_pending. A reason is required. Use dryRun=true to run the same checks (reason, key allowed to decide, still pending) and get the approval as it would end, without deciding or running anything.\n\nRequired scope: `approvals:write`.", "operationId": "approvals.approve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the approval (apr_…).", "schema": { "type": "string", "pattern": "^apr_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideApproval" }, "example": { "reason": "Within the refund policy: order delivered damaged.", "actor": { "id": "user_8841", "role": "staff" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed", "preview" ], "description": "pending waits for a decision. approved, executing, executed and failed follow an approval: the action runs only after it. rejected, expired and canceled never run it. preview only appears in the answer of approve with dryRun=true: the approval as it is now, with the decision that would be recorded; nothing was decided or run." }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ], "example": "cse_5RvP2aKq9XwLmN3tYbZc01" }, "tool": { "type": "string", "example": "issue_refund", "description": "The name of the action or tool the agent wants to run." }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The exact arguments the action will run with if approved. Null when the tool is noPersist: those are kept encrypted and shown to nobody." }, "summary": { "type": "string", "description": "A line for a person to read. For a noPersist tool it is only the name." }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", "policy_not_required", null ], "description": "Why it needed approval: policy_always, policy_condition (the condition on its arguments held), policy_accumulated (the sum for this contact in the period passed the limit) or policy_rule (a rule of the policy asked for it: see ruleIndex)." }, "ruleIndex": { "type": [ "integer", "null" ], "description": "The position (from 0) of the rule of the policy that decided this, when reasonCode is policy_rule. Null otherwise." }, "automatedDecision": { "type": "boolean", "description": "True when the policy marks this as an automated decision about a person (Ley 21.719, art. 8 bis). The person may ask for a review." }, "dataSeen": { "description": "The names of the argument fields the approver was shown. Never their values.", "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "$ref": "#/components/schemas/Approver" } }, "requestedByKeyId": { "type": [ "string", "null" ], "description": "The API key whose turn proposed the action, if any. It can never decide this request." }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalDecision" }, { "type": "null" } ] }, "result": { "type": [ "string", "null" ], "description": "What the action returned once it ran. Truncated." }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ], "description": "What the person said when they asked for the review: their point of view on the decision. Null if they gave none or no review was asked." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:write" ] } ], "summary": "Approve an action", "tags": [ "Approvals" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "approvals:write" ] } }, "/v2/approvals/{id}/reject": { "post": { "description": "Rejects the request: the action never runs and the agent tells the person it was not done. Same rules as approve: the policy must name this key, and a request is decided once (409 approval_not_pending after that). A reason is required.\n\nRequired scope: `approvals:write`.", "operationId": "approvals.reject", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the approval (apr_…).", "schema": { "type": "string", "pattern": "^apr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideApproval" }, "example": { "reason": "Above the limit of the refund policy.", "actor": { "id": "user_8841", "role": "staff" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:write" ] } ], "summary": "Reject an action", "tags": [ "Approvals" ], "x-lelemon-effect": "write", "x-required-scopes": [ "approvals:write" ] } }, "/v2/approvals/{id}/request-review": { "post": { "description": "Use it when the person affected by a decision asks for it to be reviewed (Ley 21.719, art. 8 bis). It works only on a decided approval whose policy has automatedDecision. It fires the approval.review_requested webhook so your team can act, and it changes nothing else. Idempotent: asking twice fires the event once.\n\nRequired scope: `approvals:write`.", "operationId": "approvals.requestReview", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the approval (apr_…).", "schema": { "type": "string", "pattern": "^apr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestApprovalReview" }, "example": { "reason": "The customer disagrees with the decision." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Approval" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:write" ] } ], "summary": "Ask for a human review of a decision", "tags": [ "Approvals" ], "x-lelemon-effect": "write", "x-required-scopes": [ "approvals:write" ] } }, "/v2/automated-decisions": { "get": { "description": "Decisions the agent took about a person with no one asked: an action it ran because its policy did not ask for a person, or one a rule of the policy refused. Only for actions whose policy has automatedDecision. Decisions that waited for a person are approvals: GET /v2/approvals. Newest first. Filter by caseId to answer a person who asks what was decided about them. Read only and safe to repeat.\n\nRequired scope: `approvals:read`.", "operationId": "automatedDecisions.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "outcome", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "allowed", "rejected" ] } }, { "name": "agentId", "required": false, "in": "query", "schema": { "example": "agt_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "name": "caseId", "required": false, "in": "query", "schema": { "example": "cse_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedDecisionList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:read" ] } ], "summary": "List automated decisions", "tags": [ "Automated decisions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "approvals:read" ] } }, "/v2/automated-decisions/{id}": { "get": { "description": "What was decided, why (reasonCode and, for a rule, its position), which argument fields it used and whether the person asked for a review. Use it to explain the decision to the person (Ley 21.719, art. 8 bis). Read only and safe to repeat.\n\nRequired scope: `approvals:read`.", "operationId": "automatedDecisions.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the automated decision (dec_…).", "schema": { "type": "string", "pattern": "^dec_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedDecision" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:read" ] } ], "summary": "Retrieve an automated decision", "tags": [ "Automated decisions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "approvals:read" ] } }, "/v2/automated-decisions/{id}/request-review": { "post": { "description": "Use it when the person affected by the decision asks for it to be reviewed or wants to give their point of view (Ley 21.719, art. 8 bis). Stores the reason they gave and fires the automated_decision.review_requested webhook so your team can act. It does not undo the decision or run anything. Idempotent: asking twice keeps the first reason and fires the event once. For a decision that waited for a person use POST /v2/approvals/{id}/request-review.\n\nRequired scope: `approvals:write`.", "operationId": "automatedDecisions.requestReview", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the automated decision (dec_…).", "schema": { "type": "string", "pattern": "^dec_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestApprovalReview" }, "example": { "reason": "The customer asks a person to review this decision." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomatedDecision" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "approvals:write" ] } ], "summary": "Ask for a human review of an automated decision", "tags": [ "Automated decisions" ], "x-lelemon-effect": "write", "x-required-scopes": [ "approvals:write" ] } }, "/v2/actions/{id}/approval-floor": { "get": { "description": "The minimum approval your platform set for a shared action, or mode never when there is none. Subaccounts that use the action cannot go below it. Read only and safe to repeat.\n\nRequired scope: `actions:read`.", "operationId": "actions.approvalFloor.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalPolicy" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:read" ] } ], "summary": "Read the approval floor of a shared action", "tags": [ "Actions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "actions:read" ] }, "put": { "description": "Only a platform, and only on an action shared with its subaccounts. The floor is the least approval any subaccount can run the action with: a call that meets it waits for the approvers you name here, whatever the policy of the subaccount says, and a subaccount cannot grant the action with mode never. The policy of the subaccount still applies on top, and the stricter one wins. Replaces the whole floor; mode never removes it. Idempotent.\n\nRequired scope: `actions:write`.", "operationId": "actions.approvalFloor.set", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the action (act_…).", "schema": { "type": "string", "pattern": "^act_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalPolicy" }, "examples": { "comparison": { "summary": "comparison", "value": { "mode": "when", "condition": { "param": "amount", "op": "gt", "value": 20000 }, "approvers": [ { "type": "role", "value": "admin" } ], "expiresInMinutes": 60 } }, "anyOf": { "summary": "anyOf", "value": { "mode": "when", "condition": { "any": [ { "param": "amount", "op": "gt", "value": 20000 }, { "param": "refund", "op": "exists" } ] }, "approvers": [ { "type": "role", "value": "admin" } ] } }, "rules": { "summary": "rules", "value": { "mode": "rules", "rules": [ { "when": { "param": "amount", "op": "gt", "value": 500000 }, "effect": "reject", "customerMessage": "A refund this large is not something we can do." }, { "when": { "param": "amount", "op": "gt", "value": 20000 }, "effect": "require_approval", "approvers": [ { "type": "role", "value": "admin" } ] } ], "accumulated": { "param": "amount", "period": "month", "limit": 50000 } } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalPolicy" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "actions:write" ] } ], "summary": "Set the approval floor of a shared action", "tags": [ "Actions" ], "x-lelemon-effect": "write", "x-required-scopes": [ "actions:write" ] } }, "/v2/team-questions": { "get": { "description": "Questions agents left for the team through the ask_team tool, newest first. Filter by status=open to build the queue of what waits for an answer. Sensitive values are covered in the question and the context. Read only and safe to repeat. To let an agent ask, grant it the ask_team tool: PUT /v2/agents/{id}/tools/ask_team.\n\nRequired scope: `team-questions:read`.", "operationId": "teamQuestions.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "open", "answered", "delivered", "discarded" ] } }, { "name": "caseId", "required": false, "in": "query", "schema": { "example": "cse_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamQuestionList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "team-questions:read" ] } ], "summary": "List team questions", "tags": [ "Team questions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "team-questions:read" ] } }, "/v2/team-questions/{id}": { "get": { "description": "The question, what the agent was trying to do, and the answer once there is one. Sensitive values are covered. Read only and safe to repeat.\n\nRequired scope: `team-questions:read`.", "operationId": "teamQuestions.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team question (tqn_…).", "schema": { "type": "string", "pattern": "^tqn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamQuestion" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "team-questions:read" ] } ], "summary": "Retrieve a team question", "tags": [ "Team questions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "team-questions:read" ] } }, "/v2/team-questions/{id}/context": { "get": { "description": "Everything a person needs to answer: the question, what the agent was trying to do, the last lines of the conversation with the customer and the data of the case. Every sensitive value is covered, in the text and in the data: only the name of the field shows. Needs the scopes team-questions:read, conversations:read and cases:read. Read only and safe to repeat.\n\nRequired scopes: `team-questions:read`, `conversations:read`, `cases:read`.", "operationId": "teamQuestions.context", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team question (tqn_…).", "schema": { "type": "string", "pattern": "^tqn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamQuestionContext" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "team-questions:read", "conversations:read", "cases:read" ] } ], "summary": "Read a team question with its context", "tags": [ "Team questions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "team-questions:read", "conversations:read", "cases:read" ] } }, "/v2/team-questions/{id}/answer": { "post": { "description": "Gives the agent the answer. The agent resumes the conversation and tells the person with its own words, through the channel of the case; nothing is forwarded raw. Use it from the tool where your team works, for example Jira. Not idempotent: a question is answered once and a second answer is 409 team_question_not_open. It does not create a knowledge document.\n\nRequired scope: `team-questions:write`.", "operationId": "teamQuestions.answer", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team question (tqn_…).", "schema": { "type": "string", "pattern": "^tqn_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerTeamQuestion" }, "example": { "answer": "The order ships on Monday. Tell them the tracking number goes by email.", "title": "Order shipping date" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamQuestion" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "team-questions:write" ] } ], "summary": "Answer a team question", "tags": [ "Team questions" ], "x-lelemon-effect": "write", "x-required-scopes": [ "team-questions:write" ] } }, "/v2/agents/{id}/runs": { "post": { "description": "The agent works on its own, outside this request, until it finishes the job or hits a limit, and answers right away with the run in progress. Follow it with GET /v2/runs/{id} or the run.* webhooks. With this scope the agent runs unattended any action it is granted, including the ones that write, as the person you declare in actor (or as your key when you declare none): your key is what vouches for them, nothing else is signed. The limits you ask for are cut to the server maximums (60 rounds and 120 minutes). If the agent has to ask something it pauses with status waiting_for_answer: answer it with POST /v2/runs/{id}/answer. Repeat the request with the same Idempotency-Key and you get the run already created, not a second one. Use dryRun=true to run the same checks (agent active and exposed, role of the actor, limits) and see the run as it would be created, without queueing anything.\n\nRequired scope: `runs:write`.", "operationId": "agents.runs.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRun" }, "example": { "goal": "Reconcile the August bank statement and tell me what is left pending.", "actor": { "id": "user_8841", "role": "staff" }, "limits": { "maxRounds": 20, "maxMinutes": 20 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ], "description": "running: working, or in the queue. waiting_for_answer: paused to ask; question has it, answer it with POST /v2/runs/{id}/answer. completed_unverified: the agent says it finished and nobody has checked it, so do not read it as done. completed: a verifier checked it (it does not happen yet). stopped: the run was cut before the agent declared the job done, by a limit (rounds, time or the spending limit Lelemon sets for every run) or because the agent never concluded (no_conclusion) or repeated itself (loop); stopReason says which and result.partial keeps the last thing the agent wrote. failed: an error; result.error says what, or stopReason abandoned if nobody answered the pause in 30 days. canceled: you canceled it." }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "Why the run ended without finishing. Set with status stopped, and with status failed for abandoned. rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ], "description": "With status waiting_for_answer, what the agent asked. Answer it with POST /v2/runs/{id}/answer." }, "rounds": { "type": "integer", "description": "Rounds taken so far." }, "limits": { "$ref": "#/components/schemas/RunLimits" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RunResult" }, { "type": "null" } ] }, "cancelRequested": { "type": "boolean", "description": "true if a cancel was asked. While a worker runs it, the run stops at the start of its next round." }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01", "description": "The scheduled task that started this run. null for a run you created with POST /v2/agents/{id}/runs." }, "actor": { "description": "The person the run works for, as declared by the key that created it. null when the run works as the key itself.", "anyOf": [ { "$ref": "#/components/schemas/RunActor" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "runs:write" ] } ], "summary": "Give an agent a job", "tags": [ "Runs" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "runs:write" ] } }, "/v2/runs": { "get": { "description": "The jobs given to agents, newest first. Filter by agentId, or by status=waiting_for_answer to build the queue of what waits for an answer. Read only and safe to repeat.\n\nRequired scope: `runs:read`.", "operationId": "runs.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "agentId", "required": false, "in": "query", "schema": { "example": "agt_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] } }, { "name": "scheduleId", "required": false, "in": "query", "description": "Only the runs started by this scheduled task.", "schema": { "example": "sch_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "runs:read" ] } ], "summary": "List runs", "tags": [ "Runs" ], "x-lelemon-effect": "read", "x-required-scopes": [ "runs:read" ] } }, "/v2/runs/{id}": { "get": { "description": "Where the run is: its status, what it spent, the question it waits on, and what the agent declared when it finished. Read only and safe to repeat.\n\nRequired scope: `runs:read`.", "operationId": "runs.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the run (run_…).", "schema": { "type": "string", "pattern": "^run_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "runs:read" ] } ], "summary": "Retrieve a run", "tags": [ "Runs" ], "x-lelemon-effect": "read", "x-required-scopes": [ "runs:read" ] } }, "/v2/runs/{id}/cancel": { "post": { "description": "If nobody is running it, it ends canceled now. If a worker is running it, cancelRequested turns true and it ends canceled when its next round starts: what it was doing finishes. A run that already ended answers 409 run_finished.\n\nRequired scope: `runs:write`.", "operationId": "runs.cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the run (run_…).", "schema": { "type": "string", "pattern": "^run_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "runs:write" ] } ], "summary": "Cancel a run", "tags": [ "Runs" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "runs:write" ] } }, "/v2/runs/{id}/answer": { "post": { "description": "The paused run resumes with your answer as context for its next round, and the agent sees who answered. Not idempotent: a question is answered once, and answering a run that is not paused answers 409 run_not_waiting.\n\nRequired scope: `runs:write`.", "operationId": "runs.answer", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the run (run_…).", "schema": { "type": "string", "pattern": "^run_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerRun" }, "example": { "answer": "Use the checking account.", "actor": { "id": "user_9020", "role": "staff" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "runs:write" ] } ], "summary": "Answer a run that asked something", "tags": [ "Runs" ], "x-lelemon-effect": "write", "x-required-scopes": [ "runs:write" ] } }, "/v2/agents/{id}/schedules": { "post": { "description": "On each date of the cron, in the timezone you send, the agent gets the goal as a run and writes first by email to the contact, with a file from one of its granted actions if it needs one. If the contact answers, the same agent keeps the conversation by email. The run is unattended: the agent never stops to ask a person, so write a goal it can finish alone. Send the contact as contactId or externalRef, exactly one; the contact needs an email address, and the agent needs the email channel and an active status. from must belong to a verified domain. A date missed while the service was down is not replayed. A contact that opted out or is outside the recipient allowlist is skipped with schedule.skipped. Three runs in a row that fail pause the task with schedule.paused. Use dryRun=true to run the same checks and see the task as it would be created, without saving it.\n\nRequired scope: `schedules:write`.", "operationId": "agents.schedules.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledTask" }, "example": { "name": "Monthly sales report", "cron": "0 9 2 * *", "timezone": "America/Santiago", "goal": "Send the sales report of the month to the contact.", "contact": { "contactId": "ctc_02y0e5MANqacVbmtn1YyeJ" }, "channel": "email", "from": "reports@acme.com", "onReply": { "instructions": "If the contact answers, help them read the report." }, "limits": { "maxRounds": 10 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "schedule" ] }, "id": { "type": "string", "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "contactId": { "type": "string", "example": "ctc_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string", "example": "Monthly sales report" }, "cron": { "type": "string", "example": "0 9 2 * *" }, "timezone": { "type": "string", "example": "America/Santiago" }, "goal": { "type": "string", "description": "What the agent is asked to do on each date." }, "channel": { "type": "string", "enum": [ "email" ] }, "from": { "type": [ "string", "null" ], "example": "reports@acme.com" }, "onReply": { "anyOf": [ { "$ref": "#/components/schemas/ScheduledTaskOnReply" }, { "type": "null" } ] }, "limits": { "description": "The limits each run gets, after the server maximums.", "type": "object", "properties": { "maxRounds": { "type": "integer", "description": "How many rounds the agent may take." }, "maxMinutes": { "type": "integer", "description": "How many minutes it may last once it starts." } }, "required": [ "maxRounds", "maxMinutes" ] }, "enabled": { "type": "boolean" }, "pausedReason": { "type": [ "string", "null" ], "enum": [ "consecutive_failures", null ], "description": "Why the platform paused the task. consecutive_failures: three runs in a row failed or were cut." }, "nextRunAt": { "type": "string", "format": "date-time", "description": "When it fires next. A date missed while it was off is not replayed." }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "agentId", "contactId", "name", "cron", "timezone", "goal", "channel", "from", "onReply", "limits", "enabled", "pausedReason", "nextRunAt", "lastRunAt", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTask" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "schedules:write" ] } ], "summary": "Schedule a job for an agent", "tags": [ "Schedules" ], "x-lelemon-effect": "write", "x-required-scopes": [ "schedules:write" ] } }, "/v2/schedules": { "get": { "description": "The scheduled tasks of your organization, newest first. Filter by agentId. Read only and safe to repeat.\n\nRequired scope: `schedules:read`.", "operationId": "schedules.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "agentId", "required": false, "in": "query", "schema": { "example": "agt_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "schedules:read" ] } ], "summary": "List scheduled tasks", "tags": [ "Schedules" ], "x-lelemon-effect": "read", "x-required-scopes": [ "schedules:read" ] } }, "/v2/schedules/{id}": { "get": { "description": "When it fires next, when it fired last and whether the platform paused it. Read only and safe to repeat.\n\nRequired scope: `schedules:read`.", "operationId": "schedules.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the schedule (sch_…).", "schema": { "type": "string", "pattern": "^sch_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTask" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "schedules:read" ] } ], "summary": "Retrieve a scheduled task", "tags": [ "Schedules" ], "x-lelemon-effect": "read", "x-required-scopes": [ "schedules:read" ] }, "patch": { "description": "Changes only what you send. A new cron or timezone recomputes nextRunAt from now. enabled false pauses it; enabled true turns it on again from now, clears a pause made by the platform and does not replay dates missed meanwhile. Safe to repeat with the same body.\n\nRequired scope: `schedules:write`.", "operationId": "schedules.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the schedule (sch_…).", "schema": { "type": "string", "pattern": "^sch_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledTask" }, "example": { "cron": "30 8 * * 1", "enabled": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTask" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "schedules:write" ] } ], "summary": "Change a scheduled task", "tags": [ "Schedules" ], "x-lelemon-effect": "write", "x-required-scopes": [ "schedules:write" ] }, "delete": { "description": "It stops firing now. Runs it already started keep going and stay readable. It cannot be undone.\n\nRequired scope: `schedules:write`.", "operationId": "schedules.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the schedule (sch_…).", "schema": { "type": "string", "pattern": "^sch_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "schedules:write" ] } ], "summary": "Delete a scheduled task", "tags": [ "Schedules" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "schedules:write" ] } }, "/v2/schedules/{id}/fire": { "post": { "description": "Use it to see a scheduled task work without waiting for its date: it starts one run of the agent as the clock would and publishes schedule.fired, or schedule.skipped when the contact cannot be written to. It sends a real email to the contact, so point the task at a contact of yours while you try it. It does not move nextRunAt and does not use up the next real date, so the task still fires on its schedule, and you can call it as many times as you need. A paused task can be fired too. Send the same Idempotency-Key to retry safely; it is required. The answer is 202: the agent works afterwards, read the run with GET /v2/runs/{id}.\n\nRequired scope: `schedules:write`.", "operationId": "schedules.fire", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the schedule (sch_…).", "schema": { "type": "string", "pattern": "^sch_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKeyRequired" } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledTaskFire" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "schedules:write" ] } ], "summary": "Fire a scheduled task now", "tags": [ "Schedules" ], "x-lelemon-effect": "write", "x-required-scopes": [ "schedules:write" ] } }, "/v2/pipelines": { "post": { "description": "Creates the pipeline active. Send stages to create them in the same call, in order; the entry stage is the one marked entry, or the first. Link an agent to a stage with agentId.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePipeline" }, "example": { "name": "Orders", "description": "From the first message to the delivery.", "stages": [ { "name": "Ordering", "entry": true, "agentId": "agt_02y0e5MANqacVbmtn1YyeJ" }, { "name": "Delivered" } ], "quickReplies": [ { "shortcut": "hours", "text": "We open from 12:00 to 24:00." } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Create a pipeline", "tags": [ "Pipelines" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "get": { "description": "Lists the pipelines of the organization, each with its stages. Use it to find where a case can start; read a stage or a field with their own routes. Read only. It is safe to repeat.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "List pipelines", "tags": [ "Pipelines" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] } }, "/v2/pipelines/{id}": { "get": { "description": "Returns one pipeline by id. Use it to refresh a single record you already know; to find records, use the list route. Stages, fields and routing rules have their own routes under it. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "Retrieve a pipeline", "tags": [ "Pipelines" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] }, "patch": { "description": "quickReplies replaces the whole list. Stages are changed on their own routes.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePipeline" }, "example": { "name": "Orders", "status": "active", "quickReplies": [ { "shortcut": "hours", "text": "We open from 12:00 to 24:00." } ], "settings": { "timezone": "America/Santiago", "autoClose": { "enabled": true, "inactivityMinutes": 120 }, "businessHours": { "days": { "mon": [ { "from": "09:00", "to": "18:00" } ] }, "holidays": [ { "date": "2026-12-25" } ] }, "waitThresholds": { "yellowMinutes": 10, "redMinutes": 30 } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Update a pipeline", "tags": [ "Pipelines" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "delete": { "description": "Answers 409 resource_in_use while it has open cases. The agents linked to its stages are not deleted.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Delete a pipeline", "tags": [ "Pipelines" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/pipelines/{id}/clone": { "post": { "description": "Copies the pipeline under a new name: its stages with their agents, required fields, transitions and settings, and its quick replies. The clone is a draft and keeps no case; set its status to active with PATCH when it is ready. Stage ids are new, and the transitions of the clone point to the new stages.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.clone", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClonePipeline" }, "example": { "name": "Orders (copy)" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Clone a pipeline", "tags": [ "Pipelines" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/pipelines/{id}/stages/reorder": { "post": { "description": "Send every stage of the pipeline in the order you want. All positions change in one operation: if the list misses a stage, repeats one or holds a stage of another pipeline, it is a 400 with param stages and nothing changes. The entry stage does not change. Returns the pipeline with its stages in the new order.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.stages.reorder", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderStages" }, "example": { "stages": [ "stg_02y0e5MANqacVbmtn1YyeJ", "stg_02y0e5MANqacVbmtn1YyeJ" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pipeline" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Reorder the stages of a pipeline", "tags": [ "Pipelines" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/pipelines/{id}/stages": { "post": { "description": "Link the agent that works the stage with agentId. Cases enter the pipeline through its entry stage, so link the agent there.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.stages.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStage" }, "example": { "name": "Ordering", "position": 1, "entry": false, "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "requiredFields": [ "address" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Create a stage", "tags": [ "Stages" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "get": { "description": "In funnel order: position 0 first, then 1, 2 and so on, the same order the stages have in the pipeline. Pages follow that order, so the first item of the first page is the first stage of the funnel.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.stages.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StageList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "List the stages of a pipeline", "tags": [ "Stages" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] } }, "/v2/pipelines/{id}/stages/{stageId}": { "get": { "description": "Returns one stage of a pipeline by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.stages.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "stageId", "required": true, "in": "path", "description": "The id of the stage (stg_…).", "schema": { "type": "string", "pattern": "^stg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "Retrieve a stage", "tags": [ "Stages" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] }, "patch": { "description": "Link or unlink the agent, set the required fields, move it or make it the entry stage.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.stages.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "stageId", "required": true, "in": "path", "description": "The id of the stage (stg_…).", "schema": { "type": "string", "pattern": "^stg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateStage" }, "example": { "name": "Ordering", "position": 2, "closes": false, "config": { "agentMode": "always" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Update a stage", "tags": [ "Stages" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "delete": { "description": "Answers 409 resource_in_use while cases are in it, and 409 conflict for the entry stage.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.stages.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "stageId", "required": true, "in": "path", "description": "The id of the stage (stg_…).", "schema": { "type": "string", "pattern": "^stg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Delete a stage", "tags": [ "Stages" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/pipelines/{id}/stages/{stageId}/set-entry": { "post": { "description": "The stage becomes the only entry stage of its pipeline and the previous one stops being it. Safe to repeat. 404 not_found when the stage is not a stage of this pipeline.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.stages.setEntry", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "stageId", "required": true, "in": "path", "description": "The id of the stage (stg_…).", "schema": { "type": "string", "pattern": "^stg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Make a stage the entry stage", "tags": [ "Stages" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/pipelines/{id}/fields": { "post": { "description": "A field holds a piece of data of the case. Select fields carry their options; a select can depend on another select.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.fields.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateField" }, "example": { "key": "address", "type": "text", "label": "Address", "required": true, "source": "agent", "instruction": "Ask for the street and the number." } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Create a field", "tags": [ "Fields" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "get": { "description": "In the order the pipeline declares them.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.fields.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "List the fields of a pipeline", "tags": [ "Fields" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] } }, "/v2/pipelines/{id}/fields/{fieldId}": { "get": { "description": "Returns one field of a pipeline by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.fields.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "fieldId", "required": true, "in": "path", "description": "The id of the field (fld_…).", "schema": { "type": "string", "pattern": "^fld_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "Retrieve a field", "tags": [ "Fields" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] }, "patch": { "description": "The key and the type are fixed. options replaces the list; cases keep the values they already have.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.fields.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "fieldId", "required": true, "in": "path", "description": "The id of the field (fld_…).", "schema": { "type": "string", "pattern": "^fld_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateField" }, "example": { "label": "Delivery address", "required": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Field" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Update a field", "tags": [ "Fields" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "delete": { "description": "Answers 409 resource_in_use while another field depends on it. It stops being required in the stages that asked for it.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.fields.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "fieldId", "required": true, "in": "path", "description": "The id of the field (fld_…).", "schema": { "type": "string", "pattern": "^fld_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Delete a field", "tags": [ "Fields" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/pipelines/{id}/routing-rules": { "post": { "description": "When a case reaches fromStageId, it goes to another pipeline: a new case is opened there (create) or the case moves (move).\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.routingRules.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRoutingRule" }, "example": { "fromStageId": "stg_02y0e5MANqacVbmtn1YyeJ", "toPipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ", "toStageId": "stg_02y0e5MANqacVbmtn1YyeJ", "mode": "move", "enabled": true } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Create a routing rule", "tags": [ "Routing rules" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "get": { "description": "Lists the routing rules of one pipeline, in the order they are evaluated. Use it before you add or reorder a rule. Read only. It is safe to repeat.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.routingRules.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRuleList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "List the routing rules of a pipeline", "tags": [ "Routing rules" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] } }, "/v2/pipelines/{id}/routing-rules/{ruleId}": { "get": { "description": "Returns one routing rule of a pipeline by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `pipelines:read`.", "operationId": "pipelines.routingRules.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "ruleId", "required": true, "in": "path", "description": "The id of the routing rule (rr_…).", "schema": { "type": "string", "pattern": "^rr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:read" ] } ], "summary": "Retrieve a routing rule", "tags": [ "Routing rules" ], "x-lelemon-effect": "read", "x-required-scopes": [ "pipelines:read" ] }, "patch": { "description": "Changes a routing rule. Send only the fields you want to change. 422 when the new values do not form a valid rule. Applying the same body twice leaves the same result. To remove a rule, delete it instead.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.routingRules.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "ruleId", "required": true, "in": "path", "description": "The id of the routing rule (rr_…).", "schema": { "type": "string", "pattern": "^rr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRoutingRule" }, "example": { "mode": "create", "enabled": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingRule" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Update a routing rule", "tags": [ "Routing rules" ], "x-lelemon-effect": "write", "x-required-scopes": [ "pipelines:write" ] }, "delete": { "description": "Removes a routing rule from its pipeline. Cases already routed stay where they are; new cases stop matching the rule. The effect is permanent through the API. Repeating the call returns 404 not_found, because the routing rule no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `pipelines:write`.", "operationId": "pipelines.routingRules.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "name": "ruleId", "required": true, "in": "path", "description": "The id of the routing rule (rr_…).", "schema": { "type": "string", "pattern": "^rr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "pipelines:write" ] } ], "summary": "Delete a routing rule", "tags": [ "Routing rules" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "pipelines:write" ] } }, "/v2/knowledge-collections": { "post": { "description": "A collection groups documents. An agent searches only the collections you give it.\n\nRequired scope: `knowledge:write`.", "operationId": "knowledgeCollections.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeCollection" }, "example": { "name": "FAQ", "description": "Questions customers ask every day." } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeCollection" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Create a collection", "tags": [ "Knowledge" ], "x-lelemon-effect": "write", "x-required-scopes": [ "knowledge:write" ] }, "get": { "description": "Newest first. Collections read by the internal assistant are not listed.\n\nRequired scope: `knowledge:read`.", "operationId": "knowledgeCollections.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeCollectionList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:read" ] } ], "summary": "List collections", "tags": [ "Knowledge" ], "x-lelemon-effect": "read", "x-required-scopes": [ "knowledge:read" ] } }, "/v2/knowledge-collections/search": { "post": { "description": "Finds the passages of your documents that answer a question, by meaning and by exact words, the same way an agent searches. Send collectionIds to search only some collections; leave it out to search all of them. Each passage says which collection and document it comes from. Read only and safe to repeat: it changes nothing. An empty data list means nothing answers it. 404 not_found when a collection does not exist or belongs to another organization; 503 service_unavailable when the search cannot run right now.\n\nRequired scope: `knowledge:read`.", "operationId": "knowledgeCollections.search", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchKnowledge" }, "example": { "query": "What is the return policy?", "limit": 5 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeSearch" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:read" ] } ], "summary": "Search the knowledge", "tags": [ "Knowledge" ], "x-lelemon-effect": "read", "x-required-scopes": [ "knowledge:read" ] } }, "/v2/knowledge-collections/{id}": { "get": { "description": "Returns one knowledge collection by id. Use it to refresh a single record you already know; to find records, use the list route. Its documents are listed on their own route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `knowledge:read`.", "operationId": "knowledgeCollections.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeCollection" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:read" ] } ], "summary": "Retrieve a collection", "tags": [ "Knowledge" ], "x-lelemon-effect": "read", "x-required-scopes": [ "knowledge:read" ] }, "patch": { "description": "Changes only what you send.\n\nRequired scope: `knowledge:write`.", "operationId": "knowledgeCollections.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeCollection" }, "example": { "name": "FAQ for customers" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeCollection" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Update a collection", "tags": [ "Knowledge" ], "x-lelemon-effect": "write", "x-required-scopes": [ "knowledge:write" ] }, "delete": { "description": "Deletes its documents and removes the collection from every agent that had it. Answers 409 resource_in_use while a connected source feeds it.\n\nRequired scope: `knowledge:write`.", "operationId": "knowledgeCollections.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Delete a collection", "tags": [ "Knowledge" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "knowledge:write" ] } }, "/v2/knowledge-collections/{id}/documents": { "post": { "description": "Send text as JSON or a file as multipart. It starts as processing; listen for knowledge_document.ready and knowledge_document.failed. Sending the same name again replaces the document and processes it again.\n\nRequired scope: `knowledge:write`.", "operationId": "knowledgeCollections.documents.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeDocument" }, "example": { "name": "horarios.md", "text": "Abrimos de 12:00 a 24:00." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateKnowledgeDocument" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocument" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Add a document", "tags": [ "Knowledge" ], "x-lelemon-effect": "write", "x-required-scopes": [ "knowledge:write" ] }, "get": { "description": "Newest first, without the content.\n\nRequired scope: `knowledge:read`.", "operationId": "knowledgeCollections.documents.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "processing", "ready", "failed" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:read" ] } ], "summary": "List documents", "tags": [ "Knowledge" ], "x-lelemon-effect": "read", "x-required-scopes": [ "knowledge:read" ] } }, "/v2/knowledge-collections/{id}/documents/{docId}": { "get": { "description": "Includes the content the agent searches once the status is ready. A failed document carries error.code.\n\nRequired scope: `knowledge:read`.", "operationId": "knowledgeCollections.documents.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "name": "docId", "required": true, "in": "path", "description": "The id of the knowledge document (kbd_…).", "schema": { "type": "string", "pattern": "^kbd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocumentWithContent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:read" ] } ], "summary": "Retrieve a document", "tags": [ "Knowledge" ], "x-lelemon-effect": "read", "x-required-scopes": [ "knowledge:read" ] }, "patch": { "description": "Rename it or replace its text. New text processes the document again. Documents kept by a connected source answer 409 resource_in_use.\n\nRequired scope: `knowledge:write`.", "operationId": "knowledgeCollections.documents.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "name": "docId", "required": true, "in": "path", "description": "The id of the knowledge document (kbd_…).", "schema": { "type": "string", "pattern": "^kbd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateKnowledgeDocument" }, "example": { "text": "Abrimos de 12:00 a 23:00." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeDocument" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Update a document", "tags": [ "Knowledge" ], "x-lelemon-effect": "write", "x-required-scopes": [ "knowledge:write" ] }, "delete": { "description": "The agent stops finding it right away. Documents kept by a connected source answer 409 resource_in_use.\n\nRequired scope: `knowledge:write`.", "operationId": "knowledgeCollections.documents.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "name": "docId", "required": true, "in": "path", "description": "The id of the knowledge document (kbd_…).", "schema": { "type": "string", "pattern": "^kbd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Delete a document", "tags": [ "Knowledge" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "knowledge:write" ] } }, "/v2/agents/{id}/knowledge-collections/{collectionId}": { "put": { "description": "Safe to repeat. The agent uses the collection from its next answer.\n\nRequired scope: `knowledge:write`.", "operationId": "agents.knowledgeCollections.grant", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "collectionId", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKnowledgeCollection" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Let an agent search a collection", "tags": [ "Knowledge" ], "x-lelemon-effect": "write", "x-required-scopes": [ "knowledge:write" ] }, "delete": { "description": "Safe to repeat: answers 204 even if the agent did not have it.\n\nRequired scope: `knowledge:write`.", "operationId": "agents.knowledgeCollections.revoke", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agent (agt_…).", "schema": { "type": "string", "pattern": "^agt_[0-9A-Za-z]{22}$" } }, { "name": "collectionId", "required": true, "in": "path", "description": "The id of the knowledge collection (kbc_…).", "schema": { "type": "string", "pattern": "^kbc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Removed." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "knowledge:write" ] } ], "summary": "Stop an agent from searching a collection", "tags": [ "Knowledge" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "knowledge:write" ] } }, "/v2/contacts": { "post": { "description": "A contact is the person the organization attends. Send externalRef to keep your own id on it: sending the same externalRef again is a 409. To create or update in one call, use PUT /v2/contacts/by-external-ref/{externalRef}.\n\nRequired scope: `contacts:write`.", "operationId": "contacts.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContact" }, "example": { "name": "Ana Pérez", "email": "ana@example.com", "phone": "+56912345678", "externalRef": "crm-4471", "companyId": "cpy_02y0e5MANqacVbmtn1YyeJ", "tags": [ "vip" ], "fields": { "plan": "pro" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:write" ] } ], "summary": "Create a contact", "tags": [ "Contacts" ], "x-lelemon-effect": "write", "x-required-scopes": [ "contacts:write" ] }, "get": { "description": "Newest first. Filter by phone, email, externalRef, or updatedSince. presence=online keeps only the contacts online now (needs the contacts:presence-read scope). To search, send q (name, email, phone, externalRef and the values of the contact fields): each result says in match which field matched. pipelineId keeps the contacts with a case in that pipeline, hasOpenCases=true the ones with an open case, fieldKey with fieldValue the ones whose contact field has that value. Any of these, or order, sorts by latest activity (or by name) instead of newest first, and adds caseCount, openCaseCount and lastActivityAt to each contact.\n\nRequired scope: `contacts:read`.", "operationId": "contacts.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "phone", "required": false, "in": "query", "description": "Exact match on the stored phone.", "schema": { "example": "+56912345678", "type": "string" } }, { "name": "email", "required": false, "in": "query", "description": "Exact match, ignoring case.", "schema": { "example": "ana@example.com", "type": "string" } }, { "name": "externalRef", "required": false, "in": "query", "schema": { "example": "crm-4471", "type": "string" } }, { "name": "updatedSince", "required": false, "in": "query", "description": "Only contacts changed at or after this moment.", "schema": { "format": "date-time", "type": "string" } }, { "name": "presence", "required": false, "in": "query", "description": "online: only contacts that are online now. Needs the contacts:presence-read scope. Answers 409 presence_not_configured when presence is not active, and 503 when the online list cannot be read.", "schema": { "type": "string", "enum": [ "online" ] } }, { "name": "q", "required": false, "in": "query", "description": "Searches name, email, phone, externalRef and the values of the contact fields, ignoring case and accents. With q the answer carries match, the field that matched.", "schema": { "example": "ana", "type": "string" } }, { "name": "pipelineId", "required": false, "in": "query", "description": "Only contacts that have a case in this pipeline.", "schema": { "example": "ppl_02y0e5MANqacVbmtn1YyeJ", "type": "string" } }, { "name": "hasOpenCases", "required": false, "in": "query", "description": "true keeps only the contacts with an open case.", "schema": { "type": "boolean", "enum": [ true ] } }, { "name": "order", "required": false, "in": "query", "description": "activity: the latest activity first. name: A to Z. Without order and without the other search parameters the list is newest first.", "schema": { "type": "string", "enum": [ "activity", "name" ] } }, { "name": "fieldKey", "required": false, "in": "query", "description": "The key of a contact field. Send it with fieldValue.", "schema": { "example": "plan", "type": "string" } }, { "name": "fieldValue", "required": false, "in": "query", "description": "Only contacts whose fieldKey has exactly this value. Send it with fieldKey.", "schema": { "example": "pro", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "List contacts", "tags": [ "Contacts" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] } }, "/v2/contacts/by-external-ref/{externalRef}": { "put": { "description": "Calling it twice with the same externalRef leaves one contact. The fields you omit stay as they were; a new contact with no name is named after the externalRef. Always answers 200.\n\nRequired scope: `contacts:write`.", "operationId": "contacts.upsertByExternalRef", "parameters": [ { "name": "externalRef", "required": true, "in": "path", "description": "Your own id for this person. The contact with this externalRef is updated; if there is none it is created.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertContact" }, "example": { "name": "Ana Pérez", "email": "ana@example.com", "phone": "+56912345678", "tags": [ "vip" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:write" ] } ], "summary": "Create or update a contact by your own id", "tags": [ "Contacts" ], "x-lelemon-effect": "write", "x-required-scopes": [ "contacts:write" ] } }, "/v2/contacts/{id}": { "get": { "description": "Returns one contact by id. Use it to refresh a single record you already know; to find records, use the list route. To search for a person, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `contacts:read`.", "operationId": "contacts.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact (ctc_…).", "schema": { "type": "string", "pattern": "^ctc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "Retrieve a contact", "tags": [ "Contacts" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] }, "patch": { "description": "Send null in email, phone or externalRef to remove it. tags replaces the whole list.\n\nRequired scope: `contacts:write`.", "operationId": "contacts.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact (ctc_…).", "schema": { "type": "string", "pattern": "^ctc_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContact" }, "example": { "email": "ana.perez@example.com", "companyId": "cpy_02y0e5MANqacVbmtn1YyeJ", "tags": [ "vip" ], "fields": { "plan": "max", "segment": null } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:write" ] } ], "summary": "Update a contact", "tags": [ "Contacts" ], "x-lelemon-effect": "write", "x-required-scopes": [ "contacts:write" ] }, "delete": { "description": "Use it when a person asks to be erased or when you decide to erase them. It is permanent: the contact, its cases, messages, files, fields, agent memory and logs lose their content; the contact is anonymized in place and what remains is an aggregate shell of each case with a new id and dates cut to the day. It does not delete rows, so statistics keep working. The erasure runs as a job: it answers 202 with a suppression to follow with GET /v2/suppressions/{id} and the contact.suppressed webhook. Without closeOpenCases it answers 409 resource_in_use while the contact has open cases. Use dryRun=true first to get the inventory without content (200, changes nothing). legalHold=true records the request and keeps everything until you repeat it without legalHold. Not idempotent in effect but safe to repeat: once started the contact answers 404.\n\nRequired scope: `contacts:erase`.", "operationId": "contacts.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact (ctc_…).", "schema": { "type": "string", "pattern": "^ctc_[0-9A-Za-z]{22}$" } }, { "name": "reason", "required": false, "in": "query", "description": "Why the contact is erased: the person asked (data_subject_request) or you decided it as the data controller (controller_instruction). It is kept in the suppression record.", "schema": { "default": "data_subject_request", "type": "string", "enum": [ "data_subject_request", "controller_instruction" ] } }, { "name": "legalHold", "required": false, "in": "query", "description": "true: you must keep this data by law (a debt, a credit, a refund). The request is recorded as held and nothing is erased until you repeat it without legalHold.", "schema": { "type": "boolean" } }, { "name": "closeOpenCases", "required": false, "in": "query", "description": "true: close the open cases of the contact and erase it. Without it, a contact with open cases is a 409 resource_in_use.", "schema": { "type": "boolean" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "dryRun=true: the inventory, nothing changes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "suppression" ] }, "id": { "type": [ "string", "null" ], "example": "sup_3PqA0x8bVw1TqS9mYp3RkL", "description": "null on a dryRun: nothing was created." }, "contactId": { "type": "string", "example": "ctc_7Hc2LmQ0x8bVw1TqS9mYp3" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed", "held", "preview" ] }, "phase": { "type": [ "string", "null" ], "enum": [ "inventory", "rows", "objects", "rest", "done", null ] }, "reason": { "type": "string", "enum": [ "data_subject_request", "controller_instruction" ] }, "legalHold": { "type": "boolean" }, "closedOpenCases": { "type": "number" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Rows erased or anonymized per store. Numbers only." }, "errorCode": { "type": [ "string", "null" ] }, "inventory": { "description": "Only on dryRun: what would be erased, by store, without content.", "anyOf": [ { "$ref": "#/components/schemas/SuppressionInventory" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "dryRun": { "type": "boolean", "description": "Present and true only on a dry run: nothing was erased and the inventory shows what would be.", "const": true } }, "required": [ "object", "id", "contactId", "status", "phase", "reason", "legalHold", "closedOpenCases", "counts", "errorCode", "inventory", "createdAt", "completedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:erase" ] } ], "summary": "Erase a contact", "tags": [ "Contacts" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "contacts:erase" ] } }, "/v2/contact-fields": { "post": { "description": "A contact field is a piece of data every contact of the organization can hold, like a plan or a customer number. Once it exists, send its value in fields when you create or update a contact.\n\nRequired scope: `contact-fields:write`.", "operationId": "contactFields.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactField" }, "example": { "key": "plan", "type": "select", "label": "Plan", "options": [ { "value": "free" }, { "value": "pro", "label": "Pro" } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactField" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contact-fields:write" ] } ], "summary": "Create a contact field", "tags": [ "Contact fields" ], "x-lelemon-effect": "write", "x-required-scopes": [ "contact-fields:write" ] }, "get": { "description": "In the order they were created.\n\nRequired scope: `contacts:read`.", "operationId": "contactFields.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactFieldList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "List the contact fields", "tags": [ "Contact fields" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] } }, "/v2/contact-fields/{id}": { "get": { "description": "Returns one contact field by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `contacts:read`.", "operationId": "contactFields.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact field (cfd_…).", "schema": { "type": "string", "pattern": "^cfd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactField" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "Retrieve a contact field", "tags": [ "Contact fields" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] }, "patch": { "description": "The key and the type are fixed. options replaces the list of a select field; contacts keep the values they already have.\n\nRequired scope: `contact-fields:write`.", "operationId": "contactFields.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact field (cfd_…).", "schema": { "type": "string", "pattern": "^cfd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactField" }, "example": { "label": "Plan contratado", "options": [ { "value": "free" }, { "value": "pro" }, { "value": "max" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactField" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contact-fields:write" ] } ], "summary": "Update a contact field", "tags": [ "Contact fields" ], "x-lelemon-effect": "write", "x-required-scopes": [ "contact-fields:write" ] }, "delete": { "description": "Removes the definition and the value it had in every contact. This cannot be undone.\n\nRequired scope: `contact-fields:write`.", "operationId": "contactFields.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact field (cfd_…).", "schema": { "type": "string", "pattern": "^cfd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contact-fields:write" ] } ], "summary": "Delete a contact field", "tags": [ "Contact fields" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "contact-fields:write" ] } }, "/v2/companies": { "post": { "description": "A company groups the contacts that work in it. Only name is required; type defaults to prospect and status to lead. rut is unique among the live companies of the organization: using one that is taken is a 409 conflict with param rut. To link a contact to the company, send companyId when you create or update the contact.\n\nRequired scope: `companies:write`.", "operationId": "companies.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCompany" }, "example": { "name": "Panadería La Espiga", "rut": "76.123.456-7", "type": "client", "status": "active", "website": "laespiga.cl", "industry": "Food", "source": "referral", "notes": "Buys flour every week." } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetail" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "companies:write" ] } ], "summary": "Create a company", "tags": [ "Companies" ], "x-lelemon-effect": "write", "x-required-scopes": [ "companies:write" ] }, "get": { "description": "The companies the organization does business with, by name. Filter by q (part of the name), status or type. A company groups the contacts that work in it.\n\nRequired scope: `contacts:read`.", "operationId": "companies.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "q", "required": false, "in": "query", "description": "Part of the name, ignoring case.", "schema": { "example": "espiga", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "lead", "active", "paused", "lost" ] } }, { "name": "type", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "prospect", "client", "partner", "vendor" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "List companies", "tags": [ "Companies" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] } }, "/v2/companies/{id}": { "get": { "description": "Returns one company by id with the ids of its contacts. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `contacts:read`.", "operationId": "companies.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the company (cpy_…).", "schema": { "type": "string", "pattern": "^cpy_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetail" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "Retrieve a company", "tags": [ "Companies" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] }, "patch": { "description": "Only the fields you send change. Send null in rut, website, industry, source or notes to remove it. A company that was lost as a business is not deleted: set its status to lost. Taking the rut of another live company is a 409 conflict with param rut.\n\nRequired scope: `companies:write`.", "operationId": "companies.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the company (cpy_…).", "schema": { "type": "string", "pattern": "^cpy_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompany" }, "example": { "status": "paused", "website": null, "notes": "Closed in January." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetail" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "companies:write" ] } ], "summary": "Update a company", "tags": [ "Companies" ], "x-lelemon-effect": "write", "x-required-scopes": [ "companies:write" ] }, "delete": { "description": "For data created by mistake: a company that was lost as a business is kept with status lost. Its contacts are not deleted: they stay and their companyId becomes null. The rut is free to use again. 404 not_found when the id does not exist or belongs to another organization.\n\nRequired scope: `companies:write`.", "operationId": "companies.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the company (cpy_…).", "schema": { "type": "string", "pattern": "^cpy_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "companies:write" ] } ], "summary": "Delete a company", "tags": [ "Companies" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "companies:write" ] } }, "/v2/lead-forms": { "post": { "description": "Creates the form active, with the key the website sends with each lead. The key is returned in secret only here and cannot be read again. A pipeline that does not exist in the organization is a 400 with param pipelineId.\n\nRequired scope: `lead-forms:write`.", "operationId": "leadForms.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadForm" }, "example": { "name": "Contacto web", "pipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ", "tags": [ "landing" ], "source": "landing_contacto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormWithSecret" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "lead-forms:write" ] } ], "summary": "Create a lead form", "tags": [ "Lead forms" ], "x-lelemon-effect": "write", "x-required-scopes": [ "lead-forms:write" ], "x-lelemon-returns-secret": true }, "get": { "description": "Lists the lead forms of the organization. It never returns their keys. Read only. It is safe to repeat.\n\nRequired scope: `lead-forms:read`.", "operationId": "leadForms.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "lead-forms:read" ] } ], "summary": "List lead forms", "tags": [ "Lead forms" ], "x-lelemon-effect": "read", "x-required-scopes": [ "lead-forms:read" ] } }, "/v2/lead-forms/{id}": { "get": { "description": "Returns one lead form by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `lead-forms:read`.", "operationId": "leadForms.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the lead form (lfm_…).", "schema": { "type": "string", "pattern": "^lfm_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadForm" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "lead-forms:read" ] } ], "summary": "Retrieve a lead form", "tags": [ "Lead forms" ], "x-lelemon-effect": "read", "x-required-scopes": [ "lead-forms:read" ] }, "patch": { "description": "Only the fields you send change. tags replaces the whole list. Set status to inactive to stop accepting leads without deleting the form. A pipeline that does not exist in the organization is a 400 with param pipelineId.\n\nRequired scope: `lead-forms:write`.", "operationId": "leadForms.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the lead form (lfm_…).", "schema": { "type": "string", "pattern": "^lfm_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadForm" }, "example": { "name": "Contacto", "status": "inactive" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadForm" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "lead-forms:write" ] } ], "summary": "Update a lead form", "tags": [ "Lead forms" ], "x-lelemon-effect": "write", "x-required-scopes": [ "lead-forms:write" ] }, "delete": { "description": "The key of the form stops working. The leads it already brought are not deleted. 404 not_found when the id does not exist or belongs to another organization.\n\nRequired scope: `lead-forms:write`.", "operationId": "leadForms.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the lead form (lfm_…).", "schema": { "type": "string", "pattern": "^lfm_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "lead-forms:write" ] } ], "summary": "Delete a lead form", "tags": [ "Lead forms" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "lead-forms:write" ] } }, "/v2/suppressions/{id}": { "get": { "description": "Use it to follow the erasure that DELETE /v2/contacts/{id} started. status is queued, running, done, failed or held; phase says where the job is. It carries counters only, never content. The webhook contact.suppressed announces the end. Read only and safe to repeat.\n\nRequired scope: `contacts:read`.", "operationId": "suppressions.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the suppression (sup_…).", "schema": { "type": "string", "pattern": "^sup_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "Retrieve a suppression", "tags": [ "Suppressions" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] } }, "/v2/cases": { "post": { "description": "Opens a case for a contact: send contactId, or contact to find or create the person in the same call (by externalRef or phone, without changing a contact that exists). Say where it starts with stageId, pipelineId (its entry stage) or agentId (the pipeline where that agent attends the entry stage). With agentId the agent needs the api channel: 422 agent_channel_disabled otherwise. To talk to a copilot (audience internal) send its agentId and the pipelineId or stageId where the case lives; the copilot answers the messages written with author contact. A contact has one open case per pipeline: 409 conflict.\n\nRequired scope: `cases:write`.", "operationId": "cases.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCase" }, "examples": { "withContactId": { "summary": "withContactId", "value": { "contactId": "ctc_02y0e5MANqacVbmtn1YyeJ", "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "pipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ", "channel": "api" } }, "withInlineContact": { "summary": "withInlineContact", "value": { "contact": { "name": "Ana Pérez", "email": "ana@example.com", "externalRef": "crm-4471" }, "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "pipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ", "channel": "api" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Open a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "get": { "description": "Newest first. This is the inbox: filter by pipelineId, stageId, status, assigneeId, contactId, control (agent or human), channel, phoneNumberId unread or presence=online (needs the contacts:presence-read scope).\n\nRequired scope: `cases:read`.", "operationId": "cases.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "pipelineId", "required": false, "in": "query", "schema": { "example": "ppl_02y0e5MANqacVbmtn1YyeJ", "type": "string" } }, { "name": "stageId", "required": false, "in": "query", "schema": { "example": "stg_02y0e5MANqacVbmtn1YyeJ", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "open", "closed" ] } }, { "name": "assigneeId", "required": false, "in": "query", "schema": { "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "type": "string" } }, { "name": "contactId", "required": false, "in": "query", "schema": { "example": "ctc_4Zq0x8bVw1TqS9mYp3RkLd", "type": "string" } }, { "name": "control", "required": false, "in": "query", "description": "human includes the cases the agent escalated.", "schema": { "type": "string", "enum": [ "agent", "human" ] } }, { "name": "channel", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "whatsapp", "api", "in_app", "email" ] } }, { "name": "phoneNumberId", "required": false, "in": "query", "schema": { "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd", "type": "string" } }, { "name": "unread", "required": false, "in": "query", "description": "true: cases with messages of the contact not read yet. false: the rest.", "schema": { "type": "boolean" } }, { "name": "presence", "required": false, "in": "query", "description": "online: only cases whose contact is online now. Needs the contacts:presence-read scope. Answers 409 presence_not_configured when presence is not active, and 503 when the online list cannot be read.", "schema": { "type": "string", "enum": [ "online" ] } }, { "name": "archived", "required": false, "in": "query", "description": "true: only archived cases. false: only the ones on the board. Omit it for both.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List cases", "tags": [ "Cases" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/cases/{id}": { "get": { "description": "Returns one case by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `cases:read`.", "operationId": "cases.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "Retrieve a case", "tags": [ "Cases" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] }, "patch": { "description": "Writes the values of fields the pipeline declares with source system. The stage, the assignee and the state change on their own routes.\n\nRequired scope: `cases:write`.", "operationId": "cases.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCase" }, "example": { "fields": { "order_number": "ORD-1042" }, "tags": [ "vip" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Update a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "delete": { "description": "Deletes a case. To keep the history, close the case instead of deleting it. The effect is permanent through the API. Repeating the call returns 404 not_found, because the case no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `cases:delete`.", "operationId": "cases.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:delete" ] } ], "summary": "Delete a case", "tags": [ "Cases" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "cases:delete" ] } }, "/v2/cases/{id}/move": { "post": { "description": "A stage of another pipeline moves the case to that pipeline, and so does pipelineId: both need the cases:reorganize scope on top of cases:write (403 scope_missing otherwise). 422 required_fields_missing, with param, when the stage requires a field the case lacks. A closed case is a 409.\n\nRequired scope: `cases:write`.", "operationId": "cases.move", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveCase" }, "examples": { "toStage": { "summary": "toStage", "value": { "stageId": "stg_02y0e5MANqacVbmtn1YyeJ" } }, "toPipeline": { "summary": "toPipeline", "value": { "pipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Move a case to a stage", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/assign": { "post": { "description": "assigneeId null leaves the case unassigned. The assignment is recorded as made by whoever issued the key. When that person is a member they can only assign to people of their own team, as in the panel: 403 forbidden otherwise.\n\nRequired scope: `cases:write`.", "operationId": "cases.assign", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignCase" }, "example": { "assigneeId": "mbr_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Assign a case to a member", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/close": { "post": { "description": "The contact can then have a new case in the pipeline. Closing a closed case is a 409.\n\nRequired scope: `cases:write`.", "operationId": "cases.close", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseCase" }, "example": { "outcome": "resolved" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Close a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/reopen": { "post": { "description": "A 409 when the case is open, or when the contact already opened another case in the pipeline.\n\nRequired scope: `cases:write`.", "operationId": "cases.reopen", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Reopen a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/take-control": { "post": { "description": "A person takes over: the agent stops answering this case and your team can write with author team. Fires case.control_changed.\n\nRequired scope: `cases:write`.", "operationId": "cases.takeControl", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Take control of a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/release-control": { "post": { "description": "The agent answers again, with the messages of the team in its context. Fires case.control_changed.\n\nRequired scope: `cases:write`.", "operationId": "cases.releaseControl", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Hand a case back to the agent", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/read": { "post": { "description": "unread goes to 0 until the contact writes again. It does not send a read receipt to the channel.\n\nRequired scope: `cases:write`.", "operationId": "cases.markRead", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Mark a case as read", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/case-queue": { "get": { "description": "The cases a member has to look at, in three lists, each with how long it has waited (only minutes inside the business hours of the pipeline) and, for waitingForPerson, a green, yellow or red color by the wait thresholds of the pipeline. waitingForPerson: the agent handed the case to a person and nobody took it, assigned to the member or without an owner. waitingForReply: cases the member escalated, in a stage whose config.attentionRole is escalation. answered: cases back in a stage whose config.attentionRole is answer, until someone writes to the customer. Each case appears once. Read only: repeating the call is safe. 404 not_found when the member does not exist in the organization.\n\nRequired scope: `cases:read`.", "operationId": "caseQueue.retrieve", "parameters": [ { "name": "memberId", "required": true, "in": "query", "description": "The member whose queue you want. It is the same list that member sees in Pending.", "schema": { "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseQueue" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "Read the attention queue of a member", "tags": [ "Case queue" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/cases/move-batch": { "post": { "description": "Moves up to 100 cases of one pipeline to a stage of that pipeline. It answers how many moved and, for each case that did not, the reason: not_found, not_in_pipeline, archived, closed, already_in_stage or required_fields_missing (with missingFields). The ones that can move move even when others cannot. To change pipeline use POST /v2/cases/{id}/move.\n\nRequired scope: `cases:reorganize`.", "operationId": "cases.moveBatch", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveCasesBatch" }, "example": { "caseIds": [ "cse_02y0e5MANqacVbmtn1YyeJ" ], "stageId": "stg_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBatchMove" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:reorganize" ] } ], "summary": "Move several cases to a stage", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:reorganize" ] } }, "/v2/cases/{id}/archive": { "post": { "description": "Takes the case off the board without deleting it or changing its status. Archiving an archived case leaves it as it is. Undo it with POST /v2/cases/{id}/unarchive.\n\nRequired scope: `cases:delete`.", "operationId": "cases.archive", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:delete" ] } ], "summary": "Archive a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:delete" ] } }, "/v2/cases/{id}/unarchive": { "post": { "description": "Puts the case back on the board with the status it had. Unarchiving a case that is not archived leaves it as it is.\n\nRequired scope: `cases:delete`.", "operationId": "cases.unarchive", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:delete" ] } ], "summary": "Bring an archived case back", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:delete" ] } }, "/v2/cases/{id}/mute": { "post": { "description": "The agent stops answering the person and every open case of the contact closes. Muting belongs to the contact, so it holds for all their cases until POST /v2/cases/{id}/unmute. Muting a muted contact leaves it muted.\n\nRequired scope: `cases:write`.", "operationId": "cases.mute", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MuteCase" }, "example": { "reason": "Sends spam" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Mute the contact of a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/unmute": { "post": { "description": "The contact can talk to the agent again. The cases that closed when it was muted stay closed: reopen the ones you need.\n\nRequired scope: `cases:write`.", "operationId": "cases.unmute", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Unmute the contact of a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/escalate": { "post": { "description": "Marks the case as needing a person, with your reason, and the agent stops answering. Fires case.control_changed with escalated true. A closed case is a 409.\n\nRequired scope: `cases:write`.", "operationId": "cases.escalate", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalateCase" }, "example": { "reason": "The person asked to talk to someone" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Case" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Hand a case to a person", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/fields/{key}/reveal": { "post": { "description": "Returns the value of a field the pipeline marks as sensitive. Reading a case never returns it. Every call writes an audit row with the key and the field, never the value, before the value is returned. The response is stored nowhere: not for idempotent replay and not in the request log. 422 field_not_sensitive when the field is not marked sensitive, or the pipeline does not declare it.\n\nRequired scope: `cases:reveal`.", "operationId": "cases.fields.reveal", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "key", "required": true, "in": "path", "description": "The key of the field, as the pipeline declares it.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevealedCaseField" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:reveal" ] } ], "summary": "Reveal a sensitive field of a case", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:reveal" ] } }, "/v2/contacts/{id}/events": { "get": { "description": "The events you reported for the contact with POST /v2/contact-events, newest first, each with what it sent or why it did not. The cases of the contact are in GET /v2/cases?contactId=.\n\nRequired scope: `triggers:read`.", "operationId": "contactEvents.listByContact", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact (ctc_…).", "schema": { "type": "string", "pattern": "^ctc_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEventList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:read" ] } ], "summary": "List the events of a contact", "tags": [ "Contact events" ], "x-lelemon-effect": "read", "x-required-scopes": [ "triggers:read" ] } }, "/v2/cases/{id}/reminders": { "post": { "description": "A task for a member of your team, due at a time. The assignee sees it in their tasks in the dashboard and gets the notice when it is due. It is signed with the author name of the API key, or its name.\n\nRequired scope: `cases:write`.", "operationId": "caseReminders.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReminder" }, "example": { "title": "Call back about the quote", "type": "call", "priority": "high", "dueAt": "2030-01-15T14:00:00.000Z", "assigneeId": "mbr_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reminder" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Add a reminder to a case", "tags": [ "Case reminders" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "get": { "description": "Newest first. Filter with status=active for the ones still to do.\n\nRequired scope: `cases:read`.", "operationId": "caseReminders.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "description": "active: pending, in_progress and overdue, the ones still to do.", "schema": { "type": "string", "enum": [ "pending", "in_progress", "overdue", "completed", "dismissed", "active" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReminderList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List the reminders of a case", "tags": [ "Case reminders" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/reminders/{id}": { "get": { "description": "Returns one reminder by id. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `cases:read`.", "operationId": "reminders.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the reminder (rem_…).", "schema": { "type": "string", "pattern": "^rem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reminder" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "Retrieve a reminder", "tags": [ "Reminders" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] }, "patch": { "description": "Changes the title, description, type, priority, due time or assignee. Applying the same body twice leaves the same result.\n\nRequired scope: `cases:write`.", "operationId": "reminders.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the reminder (rem_…).", "schema": { "type": "string", "pattern": "^rem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateReminder" }, "example": { "dueAt": "2030-01-16T14:00:00.000Z" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reminder" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Edit a reminder", "tags": [ "Reminders" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "delete": { "description": "Deletes the reminder. The effect is permanent through the API. Repeating the call returns 404 not_found, because the reminder no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `cases:write`.", "operationId": "reminders.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the reminder (rem_…).", "schema": { "type": "string", "pattern": "^rem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Delete a reminder", "tags": [ "Reminders" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "cases:write" ] } }, "/v2/reminders/{id}/complete": { "post": { "description": "Marks it done, with an optional note of what happened. The key is saved as who completed it.\n\nRequired scope: `cases:write`.", "operationId": "reminders.complete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the reminder (rem_…).", "schema": { "type": "string", "pattern": "^rem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompleteReminder" }, "example": { "completionNote": "Talked to them." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reminder" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Complete a reminder", "tags": [ "Reminders" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/reminders/{id}/dismiss": { "post": { "description": "The task is not needed anymore. It stays in the list.\n\nRequired scope: `cases:write`.", "operationId": "reminders.dismiss", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the reminder (rem_…).", "schema": { "type": "string", "pattern": "^rem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reminder" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Dismiss a reminder", "tags": [ "Reminders" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/presence-signals": { "post": { "description": "Use it from your backend to tell Lelemon which of your users are in your app, so the team sees them as online or as last seen. Send up to 100 signals per call, identified by the externalRef of the contact: state active about every 60 seconds while the person is in your app, and offline when they leave. A contact is online while its last active signal is less than 120 seconds old. It answers 202 with only how many signals matched a contact of this organization, never which ones, and it does not create contacts: create them first with PUT /v2/contacts/by-external-ref/{externalRef}. It stores only the last signal of each contact, no history, and sends no webhook. Presence shows in contacts and cases once the organization setting presenceEnabled is on. Sending the same signal twice is harmless.\n\nRequired scope: `contacts:presence`.", "operationId": "presence.reportSignals", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportPresenceSignals" }, "example": { "signals": [ { "externalRef": "crm-4471", "state": "active" } ] } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceSignalsResult" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:presence" ] } ], "summary": "Report who is online in your app", "tags": [ "Presence" ], "x-lelemon-effect": "write", "x-required-scopes": [ "contacts:presence" ] } }, "/v2/presence/settings": { "get": { "description": "Use it to know why presence does not show: it needs enabled true and hasSignals true. It reads the organization or subaccount the key acts on.\n\nRequired scope: `presence:configure`.", "operationId": "presence.settings.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceSettings" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "presence:configure" ] } ], "summary": "Read the presence setting", "tags": [ "Presence" ], "x-lelemon-effect": "read", "x-required-scopes": [ "presence:configure" ] }, "put": { "description": "Sets the organization setting presenceEnabled for the organization or subaccount the key acts on. Turn it on before reading presence or filtering contacts and cases with presence=online, which answer 409 presence_not_configured while it is off. Turning it off hides presence but keeps the stored signals. Idempotent: the same body leaves the same setting.\n\nRequired scope: `presence:configure`.", "operationId": "presence.settings.update", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePresenceSettings" }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PresenceSettings" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "presence:configure" ] } ], "summary": "Turn presence on or off", "tags": [ "Presence" ], "x-lelemon-effect": "write", "x-required-scopes": [ "presence:configure" ] } }, "/v2/organization": { "get": { "description": "The name and slug of the organization or subaccount the key acts on.\n\nRequired scope: `organization:read`.", "operationId": "organization.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "organization:read" ] } ], "summary": "Get the organization", "tags": [ "Organization" ], "x-lelemon-effect": "read", "x-required-scopes": [ "organization:read" ] }, "patch": { "description": "Changes the name, with the same rule as the panel. Only a key issued by the owner can use it. Idempotent: the same body leaves the same name.\n\nRequired scope: `organization:write`.", "operationId": "organization.update", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBasicInfo" }, "example": { "name": "Panadería Ana" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "organization:write" ] } ], "summary": "Rename the organization", "tags": [ "Organization" ], "x-lelemon-effect": "write", "x-required-scopes": [ "organization:write" ] } }, "/v2/organization/settings": { "get": { "description": "Business hours, inactivity closing, presence, trace storage and branding of the organization or subaccount the key acts on.\n\nRequired scope: `organization:read`.", "operationId": "organization.settings.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettings" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "organization:read" ] } ], "summary": "Get the organization settings", "tags": [ "Organization" ], "x-lelemon-effect": "read", "x-required-scopes": [ "organization:read" ] }, "patch": { "description": "Merges the fields you send into the settings, with the same validation as the panel: business hours need a timezone, start and end hour from 0 to 23, and Saturday and Sunday flags. Send cerrarTrasDiasSinActividad null to turn the inactivity closing off. Idempotent: the same body leaves the same settings.\n\nRequired scope: `settings:write`.", "operationId": "organization.settings.update", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettings" }, "example": { "businessHours": { "timezone": "America/Santiago", "startHour": 9, "endHour": 18, "activeSaturday": false, "activeSunday": false }, "cerrarTrasDiasSinActividad": 30 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationSettings" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "settings:write" ] } ], "summary": "Change the organization settings", "tags": [ "Organization" ], "x-lelemon-effect": "write", "x-required-scopes": [ "settings:write" ] } }, "/v2/organization/company-profile": { "get": { "description": "What the agents know about the business: name, description, contact, schedule, services, FAQ and custom instructions.\n\nRequired scope: `organization:read`.", "operationId": "organization.companyProfile.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProfile" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "organization:read" ] } ], "summary": "Get the company profile", "tags": [ "Organization" ], "x-lelemon-effect": "read", "x-required-scopes": [ "organization:read" ] }, "patch": { "description": "Merges the fields you send into the profile; services and faq are replaced whole. Same validation as the panel. Idempotent: the same body leaves the same profile.\n\nRequired scope: `settings:write`.", "operationId": "organization.companyProfile.update", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompanyProfile" }, "example": { "businessName": "Panadería Ana", "schedule": "Lunes a viernes, 9 a 18", "services": [ { "name": "Pan de masa madre", "description": "Horneado cada día." } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyProfile" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "settings:write" ] } ], "summary": "Change the company profile", "tags": [ "Organization" ], "x-lelemon-effect": "write", "x-required-scopes": [ "settings:write" ] } }, "/v2/cases/{id}/notes": { "post": { "description": "Internal: only the team sees it. It is signed with authorName when you send it (the person who writes), otherwise with the author name of the API key, or its name.\n\nRequired scope: `cases:write`.", "operationId": "caseNotes.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNote" }, "example": { "content": "Call back on Monday.", "authorName": "Ana Pérez" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Add a note to a case", "tags": [ "Case notes" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "get": { "description": "Newest first.\n\nRequired scope: `cases:read`.", "operationId": "caseNotes.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List the notes of a case", "tags": [ "Case notes" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/cases/{id}/notes/{noteId}": { "get": { "description": "Returns one internal note of a case by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `cases:read`.", "operationId": "caseNotes.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "noteId", "required": true, "in": "path", "description": "The id of the note (not_…).", "schema": { "type": "string", "pattern": "^not_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "Retrieve a note", "tags": [ "Case notes" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] }, "patch": { "description": "Edits the text of an internal note. The contact never sees notes. Applying the same body twice leaves the same result.\n\nRequired scope: `cases:write`.", "operationId": "caseNotes.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "noteId", "required": true, "in": "path", "description": "The id of the note (not_…).", "schema": { "type": "string", "pattern": "^not_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNote" }, "example": { "content": "Call back on Tuesday." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Edit a note", "tags": [ "Case notes" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "delete": { "description": "Deletes an internal note of a case. The effect is permanent through the API. Repeating the call returns 404 not_found, because the note no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `cases:write`.", "operationId": "caseNotes.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "noteId", "required": true, "in": "path", "description": "The id of the note (not_…).", "schema": { "type": "string", "pattern": "^not_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Delete a note", "tags": [ "Case notes" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/attachments": { "post": { "description": "Multipart, with the file in the file field. PDF, images, Word, Excel, CSV, XML and text, up to 10 MB.\n\nRequired scope: `cases:write`.", "operationId": "caseAttachments.upload", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Upload a file to a case", "tags": [ "Case attachments" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] }, "get": { "description": "Newest first.\n\nRequired scope: `cases:read`.", "operationId": "caseAttachments.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List the files of a case", "tags": [ "Case attachments" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/cases/{id}/attachments/{attachmentId}": { "get": { "description": "Returns one file of a case by id. Use it to refresh a single record you already know; to find records, use the list route. To get the bytes, use the download route of the file. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `cases:read`.", "operationId": "caseAttachments.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "attachmentId", "required": true, "in": "path", "description": "The id of the attachment (att_…).", "schema": { "type": "string", "pattern": "^att_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Attachment" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "Retrieve a file of a case", "tags": [ "Case attachments" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] }, "delete": { "description": "Deletes a file attached to a case. Messages that already carried it keep their record. The effect is permanent through the API. Repeating the call returns 404 not_found, because the file no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `cases:write`.", "operationId": "caseAttachments.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "attachmentId", "required": true, "in": "path", "description": "The id of the attachment (att_…).", "schema": { "type": "string", "pattern": "^att_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Delete a file of a case", "tags": [ "Case attachments" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/attachments/{attachmentId}/download": { "get": { "description": "A signed link that lasts 10 minutes. Ask again for a new one.\n\nRequired scope: `cases:read`.", "operationId": "caseAttachments.download", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "attachmentId", "required": true, "in": "path", "description": "The id of the attachment (att_…).", "schema": { "type": "string", "pattern": "^att_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachmentDownload" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "Get the download link of a file", "tags": [ "Case attachments" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/files": { "post": { "description": "Multipart, with the file in the file field and the purpose next to it. Upload once, then use the returned id as fileId in a message, a campaign or a template header: the file goes to WhatsApp for you when it is sent. The purpose sets the accepted types and sizes, which are the ones WhatsApp takes: message_media and campaign_media take JPEG and PNG images up to 5 MB, MP4 and 3GPP video up to 16 MB, and PDF, text, Word, Excel and PowerPoint documents up to 100 MB; template_header takes JPEG, PNG, MP4 and PDF samples. The type is read from the content, so a PNG sent as image/jpeg is rejected. A file only works where its purpose says: one uploaded for campaign_media is not accepted in a single message. Send contactId (with message_media) for a document that carries one person data, such as a statement: it can only be sent to that contact and it is erased with them. With dryRun=true it validates the file and the purpose, answers what it would return and stores nothing. Repeating the call with the same Idempotency-Key returns the first file.\n\nRequired scope: `files:write`.", "operationId": "files.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "purpose" ], "properties": { "file": { "type": "string", "format": "binary" }, "purpose": { "type": "string", "enum": [ "message_media", "template_header", "campaign_media" ] }, "contactId": { "type": "string" } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "file" ] }, "id": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Use it as fileId in a message, a campaign or a template header." }, "purpose": { "type": "string", "enum": [ "message_media", "template_header", "campaign_media" ], "description": "What the file is for. message_media: the image, video or document of one WhatsApp message. campaign_media: the same, for a campaign. template_header: the sample file WhatsApp reviews in a template header. The purpose sets which types and sizes are accepted, and a file only works where its purpose says." }, "filename": { "type": "string", "example": "promo.jpg" }, "mimeType": { "type": "string", "example": "image/jpeg", "description": "The type found in the content, not the one the client sent." }, "sizeBytes": { "type": "integer", "example": 184320 }, "sha256": { "type": "string", "example": "a3f1c0d2e4b5a6978877665544332211a3f1c0d2e4b5a6978877665544332211", "description": "SHA-256 of the content, in hex." }, "contactId": { "type": [ "string", "null" ], "example": null, "description": "The contact the file is about, or null." }, "createdAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "purpose", "filename", "mimeType", "sizeBytes", "sha256", "contactId", "createdAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "files:write" ] } ], "summary": "Upload a file", "tags": [ "Files" ], "x-lelemon-effect": "write", "x-required-scopes": [ "files:write" ] }, "get": { "description": "Newest first. Filter by purpose. Read only; it does not return the bytes.\n\nRequired scope: `files:read`.", "operationId": "files.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "purpose", "required": false, "in": "query", "description": "Only the files uploaded for this purpose.", "schema": { "type": "string", "enum": [ "message_media", "template_header", "campaign_media" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "files:read" ] } ], "summary": "List files", "tags": [ "Files" ], "x-lelemon-effect": "read", "x-required-scopes": [ "files:read" ] } }, "/v2/files/{id}": { "get": { "description": "Returns the record of one file: its purpose, type, size and hash. Use it to check a file before you send it. 404 not_found when the id does not exist, was deleted or belongs to another organization. Read only, so you can repeat it safely.\n\nRequired scope: `files:read`.", "operationId": "files.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the file (fil_…).", "schema": { "type": "string", "pattern": "^fil_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/File" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "files:read" ] } ], "summary": "Retrieve a file", "tags": [ "Files" ], "x-lelemon-effect": "read", "x-required-scopes": [ "files:read" ] }, "delete": { "description": "Deletes the stored file for good. Messages that already went out keep their record. If a campaign that has not finished or a message that has not gone out uses it, it answers 409 resource_in_use: cancel that campaign or wait, then delete again. Repeating the call returns 404 not_found, because the file no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `files:write`.", "operationId": "files.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the file (fil_…).", "schema": { "type": "string", "pattern": "^fil_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "files:write" ] } ], "summary": "Delete a file", "tags": [ "Files" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "files:write" ] } }, "/v2/cases/{id}/messages": { "get": { "description": "The whole thread: the contact, the agent, your team and the internal notes (visibility internal). Newest first by default; order=asc reads it from the start. Files of the contact come with a signed url.\n\nRequired scope: `cases:read`.", "operationId": "caseMessages.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "order", "required": false, "in": "query", "description": "desc is the newest first. asc reads the thread from the start.", "schema": { "default": "desc", "type": "string", "enum": [ "desc", "asc" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List the messages of a case", "tags": [ "Case messages" ], "x-lelemon-effect": "read", "x-lelemon-open-world": true, "x-required-scopes": [ "cases:read" ] }, "post": { "description": "author contact needs cases:converse: the agent answers on its own and the answer reaches you by the message.created webhook; when the agent finishes its turn you also get case.turn_completed. If a monthly budget is spent it answers 402 budget_exceeded and nothing is saved: stop and do not retry until the month resets or the limit is raised. author team needs cases:send and a person in control (409 case_agent_in_control otherwise); 422 channel_window_closed on WhatsApp after 24 hours without the person, 422 no_outbound_channel when the case cannot be written back. visibility internal leaves a note for the team and needs only cases:write. attachmentIds sends files already uploaded to the case. interactive sends buttons, a list, a product, a product list or the catalog instead of text, on WhatsApp cases inside the 24 hours window; the tap of the person comes back as a message with reply {id, title}, and a cart as a message with order. Each call sends a new message: use an Idempotency-Key to retry safely. Use dryRun=true first to run the same checks (author scope, case, budget, who is in control, channel, allowlist, 24 hours window, attachments) and get 200 with the message as it would be created, with nothing sent or saved; its id is not saved and attachments comes empty.\n\nRequired scope: `cases:write`.", "operationId": "caseMessages.create", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMessage" }, "examples": { "fromContact": { "summary": "fromContact", "value": { "author": "contact", "text": "Where is my order?", "actor": { "id": "user_8841", "role": "staff" } } }, "teamText": { "summary": "teamText", "value": { "author": "team", "text": "Your order leaves today.", "authorName": "Ana Pérez", "visibility": "public" } }, "teamInteractive": { "summary": "teamInteractive", "value": { "author": "team", "interactive": { "type": "buttons", "body": "Do you want to confirm the order?", "buttons": [ { "id": "yes", "title": "Yes" }, { "id": "no", "title": "No" } ] }, "authorName": "Ana Pérez" } }, "teamFiles": { "summary": "teamFiles", "value": { "author": "team", "attachmentIds": [ "att_02y0e5MANqacVbmtn1YyeJ" ] } }, "interactiveList": { "summary": "interactiveList", "value": { "author": "team", "interactive": { "type": "list", "body": "Pick a time for the delivery.", "list": { "button": "See times", "sections": [ { "title": "Tomorrow", "rows": [ { "id": "am", "title": "Morning", "description": "9:00 to 12:00" }, { "id": "pm", "title": "Afternoon" } ] } ] } }, "authorName": "Ana Pérez" } }, "interactiveProduct": { "summary": "interactiveProduct", "value": { "author": "team", "interactive": { "type": "product", "product": { "catalogId": "1234567890", "productId": "sku-1042" } }, "authorName": "Ana Pérez" } }, "interactiveProductList": { "summary": "interactiveProductList", "value": { "author": "team", "interactive": { "type": "product_list", "header": "Our coffees", "body": "Pick what you want.", "products": { "catalogId": "1234567890", "sections": [ { "title": "Coffee", "productIds": [ "sku-1042", "sku-1043" ] } ] } }, "authorName": "Ana Pérez" } }, "interactiveCatalog": { "summary": "interactiveCatalog", "value": { "author": "team", "interactive": { "type": "catalog", "body": "See everything we sell." }, "authorName": "Ana Pérez" } }, "interactiveCtaUrl": { "summary": "interactiveCtaUrl", "value": { "author": "team", "interactive": { "type": "cta_url", "body": "Track your order here.", "cta": { "displayText": "Track order", "url": "https://example.com/orders/1042" } }, "authorName": "Ana Pérez" } }, "interactiveFlow": { "summary": "interactiveFlow", "value": { "author": "team", "interactive": { "type": "flow", "body": "Fill in your address.", "flow": { "flowId": "1234567890", "cta": "Open form" } }, "authorName": "Ana Pérez" } }, "interactiveLocationRequest": { "summary": "interactiveLocationRequest", "value": { "author": "team", "interactive": { "type": "location_request", "body": "Send us your location for the delivery." }, "authorName": "Ana Pérez" } }, "interactiveContactRequest": { "summary": "interactiveContactRequest", "value": { "author": "team", "interactive": { "type": "contact_request", "body": "Share your contact so we can reach you." }, "authorName": "Ana Pérez" } }, "interactiveCall": { "summary": "interactiveCall", "value": { "author": "team", "interactive": { "type": "call", "body": "Call us if you prefer.", "call": { "displayText": "Call now" } }, "authorName": "Ana Pérez" } }, "interactiveCarousel": { "summary": "interactiveCarousel", "value": { "author": "team", "interactive": { "type": "carousel", "body": "Our best sellers.", "carousel": { "cards": [ { "header": { "type": "image", "url": "https://example.com/coffee.jpg" }, "body": "House coffee", "cta": { "displayText": "Buy", "url": "https://example.com/coffee" } } ] } }, "authorName": "Ana Pérez" } } } } } }, "responses": { "200": { "description": "dryRun=true: the message as it would be created; nothing is sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "message" ] }, "id": { "type": "string", "example": "msg_4Zq0x8bVw1TqS9mYp3RkLd" }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "author": { "type": "string", "enum": [ "contact", "agent", "team" ] }, "authorName": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "text": { "type": "string" }, "contentType": { "type": "string", "example": "text" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" } }, "interactive": { "description": "The buttons, list, product or catalog the message carried. null on any other message.", "anyOf": [ { "$ref": "#/components/schemas/Interactive" }, { "type": "null" } ] }, "reply": { "description": "Set when the person tapped a button or a list row: the id and title they tapped. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageReply" }, { "type": "null" } ] }, "order": { "description": "Set when the person sent a cart from the WhatsApp catalog. text carries their note. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageOrder" }, { "type": "null" } ] }, "location": { "description": "Set when the person shared a location (answering a location_request or on their own). text carries it as a sentence the agent reads. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageLocation" }, { "type": "null" } ] }, "flowResponse": { "description": "Set when the person finished a WhatsApp Flow: the fields they filled in. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageFlowResponse" }, { "type": "null" } ] }, "contact": { "description": "Set when the person shared their phone answering a contact_request. A contact card the person forwards on their own is not kept. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageContact" }, { "type": "null" } ] }, "error": { "description": "Set when status is failed: why. null on any other status. Read it to know whether to retry, send a template (outside the 24-hour window) or stop.", "anyOf": [ { "$ref": "#/components/schemas/MessageError" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed" ], "description": "Delivery to the channel of the case." }, "createdAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "caseId", "author", "authorName", "visibility", "text", "contentType", "attachments", "status", "createdAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "The monthly budget is spent. Stop; do not retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Add a message to a case", "tags": [ "Case messages" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/messages/{messageId}/redact": { "post": { "description": "Use it when a message holds data that must not stay, for example an ID number or a password the person typed. The text is replaced by [redacted] and the file, transcription and copies of the message in logs, events and agent memory are erased. The rest of the thread stays. It cannot be undone. It is idempotent: redacting a redacted message answers 200 with the same message and publishes nothing. Publishes the webhook message.redacted, which carries ids only: pass it on to every system where you copied the message.\n\nRequired scope: `cases:delete`.", "operationId": "caseMessages.redact", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "messageId", "required": true, "in": "path", "description": "The id of the message (msg_…).", "schema": { "type": "string", "pattern": "^msg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:delete" ] } ], "summary": "Redact a message", "tags": [ "Case messages" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "cases:delete" ] } }, "/v2/cases/{id}/turns": { "get": { "description": "Use it to see which tools the agent called in a case, with what input and what output, how many tokens each turn spent and which model answered. Newest first. Input and output are masked by shape (emails, RUTs, phones, cards, secrets) and a tool marked noPersist leaves only its status and duration. Traces are kept 90 days; an organization with the noPersistTraces setting keeps none. Read-only and idempotent. Do not use it to read the conversation: use GET /v2/cases/{id}/messages. To know when a turn ends without polling, subscribe to the case.turn_completed event.\n\nRequired scope: `turns:read`.", "operationId": "caseTurns.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TurnList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "turns:read" ] } ], "summary": "List the turns the agent took in a case", "tags": [ "Case turns" ], "x-lelemon-effect": "read", "x-lelemon-open-world": true, "x-required-scopes": [ "turns:read" ] } }, "/v2/usage": { "get": { "description": "Use it to bill your own customers or to see where tokens go: turns, replies and tokens per day, agent, model or subaccount over a date range of up to 366 days. A platform key reads one subaccount with the Lelemon-Subaccount header, or all of them at once with groupBy=subaccount, which also counts the usage of the platform itself as the group with subaccountId null. Days count in the time zone of the organization. It shows no prices. Read-only and idempotent. Do not use it to enforce a limit: for that create a budget with POST /v2/budgets.\n\nRequired scope: `usage:read`.", "operationId": "usage.retrieve", "parameters": [ { "name": "from", "required": false, "in": "query", "description": "First day, inclusive, as YYYY-MM-DD in the time zone of the organization. Defaults to the first day of the current month.", "schema": { "example": "2026-11-01", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "Last day, inclusive. Defaults to today. The range cannot pass 366 days.", "schema": { "example": "2026-11-30", "type": "string" } }, { "name": "agentId", "required": false, "in": "query", "description": "Only the usage of this agent.", "schema": { "example": "agt_7Hc2LmQ0x8bVw1TqS9mYp3", "type": "string" } }, { "name": "groupBy", "required": false, "in": "query", "description": "Split data by day, agent or model. subaccount splits by subaccount and only works with a platform key that does not send Lelemon-Subaccount: it covers the platform and all its subaccounts, the group with subaccountId null is the platform itself and the totals are the sum of every group. Without it data is empty and the totals are those of the organization of the key.", "schema": { "type": "string", "enum": [ "day", "agent", "model", "subaccount" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "usage:read" ] } ], "summary": "Get the usage of your agents", "tags": [ "Usage" ], "x-lelemon-effect": "read", "x-required-scopes": [ "usage:read" ] } }, "/v2/case-metrics": { "get": { "description": "One row per case whose last change fell in from..to, oldest change first, so you can sync the rows into your own reports page by page. Each row tells when the case came in, was handed to a person, was taken and was closed, who closed it (agent, person or system), whether the agent resolved it alone, and the seconds spent with the agent and with a person. The range is at most 31 days. A platform key reads one subaccount with the Lelemon-Subaccount header. The panel shows the same numbers. Read-only and idempotent.\n\nRequired scope: `cases:read`.", "operationId": "caseMetrics.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "from", "required": true, "in": "query", "description": "Start of the range, inclusive, as an ISO 8601 date and time with its zone. The range filters by the last change of the case: its entry, handoff, takeover, closing or reopening.", "schema": { "example": "2026-11-02T13:00:00Z", "type": "string" } }, { "name": "to", "required": false, "in": "query", "description": "End of the range, not included. Defaults to now. It can be at most 31 days after from.", "schema": { "example": "2026-11-02T14:00:00Z", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseMetricsList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List the times of the cases that changed in a range", "tags": [ "Case metrics" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } }, "/v2/budgets": { "post": { "description": "Use it to cap what agents can spend per month, in US dollars, for the whole organization, one subaccount, one agent or one contact. A contact budget keeps a stranger from using up the budget of everyone. At the alert percent (80 by default) the budget.threshold_reached event fires once; at the limit, with enforcement stop (the default), the agent stops and POST /v2/cases/{id}/messages answers 402 budget_exceeded until the month resets or you raise the limit. With enforcement notify the agent never stops and only the events fire. The month is counted in the time zone of the organization. Several budgets can apply to the same turn and the strictest one stops it. Creates one budget per scope and subject: a second one answers 409. Not idempotent. Do not use it to change an existing budget: use PATCH /v2/budgets/{id}.\n\nRequired scope: `budgets:write`.", "operationId": "budgets.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBudget" }, "example": { "scope": "agent", "subjectId": "agt_02y0e5MANqacVbmtn1YyeJ", "monthlyLimitConversations": 500, "alertPercent": 80, "enforcement": "stop" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "budgets:write" ] } ], "summary": "Create a monthly budget", "tags": [ "Budgets" ], "x-lelemon-effect": "write", "x-required-scopes": [ "budgets:write" ] }, "get": { "description": "Use it to see every budget the key can manage with what is spent this month. Newest first. Read-only and idempotent.\n\nRequired scope: `budgets:read`.", "operationId": "budgets.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "budgets:read" ] } ], "summary": "List the budgets", "tags": [ "Budgets" ], "x-lelemon-effect": "read", "x-required-scopes": [ "budgets:read" ] } }, "/v2/budgets/{id}": { "get": { "description": "Use it to check how much of a budget is spent this month and its state. Read-only and idempotent.\n\nRequired scope: `budgets:read`.", "operationId": "budgets.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the budget (bgt_…).", "schema": { "type": "string", "pattern": "^bgt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "budgets:read" ] } ], "summary": "Get a budget", "tags": [ "Budgets" ], "x-lelemon-effect": "read", "x-required-scopes": [ "budgets:read" ] }, "patch": { "description": "Use it to raise or lower the limit, change the alert percent or switch between stop and notify. Raising the limit above what is spent makes a stopped agent answer again at once and re-arms the alert. The scope and the subject cannot change: create another budget instead. A key of a subaccount only reaches the budgets of its own organization; the budget that its platform set for it is not visible to it and cannot be raised from there. Idempotent: the same body leaves the same budget.\n\nRequired scope: `budgets:write`.", "operationId": "budgets.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the budget (bgt_…).", "schema": { "type": "string", "pattern": "^bgt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBudget" }, "example": { "monthlyLimitConversations": 750, "enforcement": "notify" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Budget" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "budgets:write" ] } ], "summary": "Change a budget", "tags": [ "Budgets" ], "x-lelemon-effect": "write", "x-required-scopes": [ "budgets:write" ] }, "delete": { "description": "Use it to remove a budget you no longer want: the agents it was stopping answer again at once and its alerts stop. The spending counted so far is deleted with it; the usage report (GET /v2/usage) is not affected. To create another budget for the same scope and subject afterwards, use POST /v2/budgets. A key of a subaccount only reaches the budgets of its own organization. Idempotent in effect: deleting it again answers 404.\n\nRequired scope: `budgets:write`.", "operationId": "budgets.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the budget (bgt_…).", "schema": { "type": "string", "pattern": "^bgt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "budgets:write" ] } ], "summary": "Delete a budget", "tags": [ "Budgets" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "budgets:write" ] } }, "/v2/members": { "get": { "description": "Use it to find the mbr_ id that POST /v2/cases/{id}/assign takes as assigneeId, and to see who is available. Read only: it does not invite, change roles, change the case scope or set availability. It returns the case scope of each member. Suspended and invited members are not listed. Newest first.\n\nRequired scope: `members:read`.", "operationId": "members.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:read" ] } ], "summary": "List the active members of the organization", "tags": [ "Members" ], "x-lelemon-effect": "read", "x-required-scopes": [ "members:read" ] } }, "/v2/members/audit-log": { "get": { "description": "The audit log of members, newest first: invitations created, resent and cancelled, role changes and removals, with who did it (the member and the API key, if it came from one), to whom, and the role before and after. Filter with member to see only what was done to one member, their invitation included. Read only. It needs members:audit-read, which only an admin or the owner can give.\n\nRequired scope: `members:audit-read`.", "operationId": "members.auditLog.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "member", "required": false, "in": "query", "description": "Only what was done to this member, including their invitation. Same id as members.list.", "schema": { "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberAuditList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:audit-read" ] } ], "summary": "List who invited, changed the role of or removed members", "tags": [ "Members" ], "x-lelemon-effect": "read", "x-required-scopes": [ "members:audit-read" ] } }, "/v2/members/{id}/availability": { "get": { "description": "status is what was marked; availableForAssignment says whether the assignment would give them a new case now, considering the opening hours of the organization. Read only and safe to repeat.\n\nRequired scope: `members:read`.", "operationId": "members.availability.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberAvailability" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:read" ] } ], "summary": "Read whether a team member is available", "tags": [ "Members" ], "x-lelemon-effect": "read", "x-required-scopes": [ "members:read" ] }, "put": { "description": "Does the same as when the person changes their own status: the assignment of new cases reads it from there. away takes them out of the assignment and drops the extension they asked for. available marks them, but if the organization has opening hours and they are closed, the automatic away by schedule still wins (availableForAssignment stays false) unless the person asked to keep going a while longer. Setting the status they already have writes nothing, so repeating the request is safe. It needs members:write: members:read does not include it.\n\nRequired scope: `members:write`.", "operationId": "members.availability.set", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMemberAvailability" }, "example": { "status": "away" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberAvailability" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:write" ] } ], "summary": "Mark a team member available or away", "tags": [ "Members" ], "x-lelemon-effect": "write", "x-required-scopes": [ "members:write" ] } }, "/v2/members/{id}/role": { "patch": { "description": "Same rule as the panel, capped by the current role of whoever issued the key: it never gives a role above that role, never touches someone with a higher role, and the owner is never changed nor named by API. The owner can set admin, member or viewer; an admin only member or viewer, and only on members and viewers. It is recorded in the audit log of members with the key. It needs members:manage.\n\nRequired scope: `members:manage`.", "operationId": "members.updateRole", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRole" }, "example": { "role": "viewer" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:manage" ] } ], "summary": "Change the role of a member", "tags": [ "Members" ], "x-lelemon-effect": "write", "x-required-scopes": [ "members:manage" ] } }, "/v2/members/{id}/case-scope": { "patch": { "description": "Same rule as the Team screen of the panel, capped by the current role of whoever issued the key: it never touches someone with a higher role (an admin changes members and viewers only), and the owner and admins always see all, so their scope cannot be set. caseScope all lets the person see every case of their pipelines, which is also what the MCP connector of Lelemon requires; null goes back to the default of the organization. Setting the value they already have writes nothing, so repeating the request is safe. It is recorded in the audit log of members with the key. It needs members:manage.\n\nRequired scope: `members:manage`.", "operationId": "members.updateCaseScope", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberCaseScope" }, "example": { "caseScope": "all" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Member" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:manage" ] } ], "summary": "Change which cases a member sees", "tags": [ "Members" ], "x-lelemon-effect": "write", "x-required-scopes": [ "members:manage" ] } }, "/v2/members/{id}": { "delete": { "description": "The person loses access and leaves their teams. The keys they issued lose their power to manage on the next call. Capped by the current role of whoever issued the key: an admin removes members and viewers only, and the owner is never removed by API. It is recorded in the audit log of members with the key. It needs members:manage.\n\nRequired scope: `members:manage`.", "operationId": "members.remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Removed." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "members:manage" ] } ], "summary": "Remove a member from the organization", "tags": [ "Members" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "members:manage" ] } }, "/v2/invitations": { "get": { "description": "Every invitation with its status (pending, accepted, expired or cancelled), email, role, who invited and when. Filter with status. Newest first. Read only: members.list shows only the people who already joined.\n\nRequired scope: `invitations:read`.", "operationId": "invitations.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "accepted", "expired", "cancelled" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "invitations:read" ] } ], "summary": "List the invitations of the organization", "tags": [ "Invitations" ], "x-lelemon-effect": "read", "x-required-scopes": [ "invitations:read" ] }, "post": { "description": "Sends the invitation email with a link that lasts 7 days. The role is capped by the current role of the person who issued the key: the owner invites up to admin, an admin invites member or viewer, nobody invites as owner. If the email cannot be sent the invitation is created anyway and emailSent is false: resend it or check the address. The acceptance link is never returned. 409 if the email already joined or has a pending invitation. It is recorded in the audit log of members with the key.\n\nRequired scope: `invitations:write`.", "operationId": "invitations.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitation" }, "example": { "email": "soporte@empresa.cl", "role": "member" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationDelivery" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "invitations:write" ] } ], "summary": "Invite a person to the organization", "tags": [ "Invitations" ], "x-lelemon-effect": "write", "x-required-scopes": [ "invitations:write" ] } }, "/v2/invitations/{id}/resend": { "post": { "description": "Renews the 7 days and sends the email again with a new link: the previous link stops working. It works on pending and expired invitations. 409 if it was accepted or cancelled. It needs a role that can give the role of the invitation.\n\nRequired scope: `invitations:write`.", "operationId": "invitations.resend", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the invitation (inv_…).", "schema": { "type": "string", "pattern": "^inv_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationDelivery" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "invitations:write" ] } ], "summary": "Resend an invitation", "tags": [ "Invitations" ], "x-lelemon-effect": "write", "x-required-scopes": [ "invitations:write" ] } }, "/v2/invitations/{id}/cancel": { "post": { "description": "The link stops working and the invitation stays listed as cancelled. The same email can be invited again. 409 if it was already accepted or cancelled. It needs a role that can give the role of the invitation.\n\nRequired scope: `invitations:write`.", "operationId": "invitations.cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the invitation (inv_…).", "schema": { "type": "string", "pattern": "^inv_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invitation" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "invitations:write" ] } ], "summary": "Cancel an invitation", "tags": [ "Invitations" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "invitations:write" ] } }, "/v2/scheduling/agendas": { "get": { "description": "The active agendas of the organization: each one has its own opening hours, meeting length and team. Use the id of one to read its availability and to book. An empty list means the organization has not set up scheduling yet. Newest first. Read only and safe to repeat.\n\nRequired scope: `scheduling:read`.", "operationId": "scheduling.agendas.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgendaList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:read" ] } ], "summary": "List the agendas", "tags": [ "Scheduling" ], "x-lelemon-effect": "read", "x-required-scopes": [ "scheduling:read" ] }, "post": { "description": "Creates an active agenda with its opening hours, meeting length and buffers. The first agenda of the organization becomes the default. Add team members to the agenda before booking: an agenda without members has no free slots. 409 conflict with param slug when another agenda already uses the slug.\n\nRequired scope: `scheduling:configure`.", "operationId": "scheduling.agendas.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgenda" }, "example": { "name": "Founder calls", "slug": "founder", "timezone": "America/Santiago", "slotDurationMinutes": 30, "availableHours": { "monday": [ { "start": "09:00", "end": "13:00" } ] } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agenda" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:configure" ] } ], "summary": "Create an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "write", "x-required-scopes": [ "scheduling:configure" ] } }, "/v2/scheduling/agendas/{id}": { "get": { "description": "The agenda with its time zone, meeting length and the window in which it accepts bookings. A paused agenda answers 404. Read only and safe to repeat.\n\nRequired scope: `scheduling:read`.", "operationId": "scheduling.agendas.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agenda (agd_…).", "schema": { "type": "string", "pattern": "^agd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agenda" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:read" ] } ], "summary": "Retrieve an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "read", "x-required-scopes": [ "scheduling:read" ] }, "patch": { "description": "Changes only the fields you send. availableHours replaces the whole week. Meetings already booked keep their time. 409 conflict with param slug when another agenda already uses the slug.\n\nRequired scope: `scheduling:configure`.", "operationId": "scheduling.agendas.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agenda (agd_…).", "schema": { "type": "string", "pattern": "^agd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgenda" }, "example": { "slotDurationMinutes": 45, "availableHours": { "monday": [ { "start": "10:00", "end": "12:00" } ] } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Agenda" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:configure" ] } ], "summary": "Update an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "write", "x-required-scopes": [ "scheduling:configure" ] } }, "/v2/scheduling/agendas/{id}/members": { "get": { "description": "The people whose calendars make the free slots of the agenda, newest first. Each one says whether a calendar the agenda can read is connected: a person without one adds no slots. An agenda with an empty list has no free slots. Read only and safe to repeat.\n\nRequired scope: `scheduling:read`.", "operationId": "scheduling.agendas.members.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agenda (agd_…).", "schema": { "type": "string", "pattern": "^agd_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgendaMemberList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:read" ] } ], "summary": "List the team of an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "read", "x-required-scopes": [ "scheduling:read" ] }, "post": { "description": "Adds an active member of the organization, who starts taking bookings from the agenda. Adding someone who is already in changes nothing and answers with their current entry: use the update route to change priority or active. The person only adds free slots once a calendar is connected. 404 not_found with param memberId when the member does not exist in the organization.\n\nRequired scope: `scheduling:configure`.", "operationId": "scheduling.agendas.members.add", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agenda (agd_…).", "schema": { "type": "string", "pattern": "^agd_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAgendaMember" }, "example": { "memberId": "mbr_02y0e5MANqacVbmtn1YyeJ", "priority": 1 } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgendaMember" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:configure" ] } ], "summary": "Add a person to the team of an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "write", "x-required-scopes": [ "scheduling:configure" ] } }, "/v2/scheduling/agendas/{id}/members/{memberId}": { "patch": { "description": "Changes only the fields you send. active false keeps the person in the agenda but stops offering their slots, active true brings them back. Meetings already booked keep their person. 404 not_found when the person is not in the agenda.\n\nRequired scope: `scheduling:configure`.", "operationId": "scheduling.agendas.members.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agenda (agd_…).", "schema": { "type": "string", "pattern": "^agd_[0-9A-Za-z]{22}$" } }, { "name": "memberId", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgendaMember" }, "example": { "active": false, "priority": 2 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgendaMember" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:configure" ] } ], "summary": "Update a person in the team of an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "write", "x-required-scopes": [ "scheduling:configure" ] }, "delete": { "description": "Takes the person out of the agenda only; they stay in the organization and their slots stop being offered. Meetings already booked keep their time. Removing someone who is not in the agenda does nothing.\n\nRequired scope: `scheduling:configure`.", "operationId": "scheduling.agendas.members.remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the agenda (agd_…).", "schema": { "type": "string", "pattern": "^agd_[0-9A-Za-z]{22}$" } }, { "name": "memberId", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Removed." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:configure" ] } ], "summary": "Remove a person from the team of an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "scheduling:configure" ] } }, "/v2/scheduling/availability": { "get": { "description": "The free slots of the agenda in the next daysAhead days (7 by default, up to 60, capped by the maxDaysAhead of the agenda), nearest first. It crosses the opening hours of the agenda with the calendars of its team, the buffers and the minimum notice. It does not say whose calendar a slot comes from or what fills the busy ones. A slot is only a promise until you book it: another booking can take it first. Read only and safe to repeat.\n\nRequired scope: `scheduling:read`.", "operationId": "scheduling.availability.retrieve", "parameters": [ { "name": "agendaId", "required": true, "in": "query", "description": "The agenda to look at. List them with GET /v2/scheduling/agendas.", "schema": { "example": "agd_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "name": "daysAhead", "required": false, "in": "query", "description": "How many days ahead to look. The maxDaysAhead of the agenda still caps it.", "schema": { "minimum": 1, "maximum": 60, "default": 7, "type": "number" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:read" ] } ], "summary": "Read the free slots of an agenda", "tags": [ "Scheduling" ], "x-lelemon-effect": "read", "x-required-scopes": [ "scheduling:read" ] } }, "/v2/scheduling/meetings": { "post": { "description": "Books the slot that starts at start: the person assigned by the agenda gets the event in their calendar and the attendee gets the invitation with the video call link, by email. It cannot be undone, only canceled: use dryRun=true first, which runs the same checks (the agenda, the recipient allowlist, that start is a free slot) and answers 200 with the meeting as it would be created, booking and sending nothing; its id is not saved. Send an Idempotency-Key so a retry does not book twice. 409 slot_not_available if someone took the slot or start is not a slot of the availability: read it again and pick another.\n\nRequired scope: `scheduling:write`.", "operationId": "scheduling.meetings.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMeeting" }, "example": { "agendaId": "agd_02y0e5MANqacVbmtn1YyeJ", "start": "2026-11-03T13:00:00.000Z", "attendeeEmail": "ana@empresa.cl", "attendeeName": "Ana Pérez", "attendeePhone": "+56912345678", "companyName": "Empresa SpA", "context": "She wants a demo of the agents for sales." } } } }, "responses": { "200": { "description": "dryRun=true: the meeting as it would be created; nothing is booked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "example": "mtg_5RvP2aKq9XwLmN3tYbZc01" }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ], "description": "scheduled is a booked meeting. canceled is closed and frees the slot." }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "number", "example": 30 }, "timezone": { "type": "string", "example": "America/Santiago" }, "attendeeEmail": { "type": "string", "example": "ana@empresa.cl" }, "attendeeName": { "type": "string", "example": "Ana Pérez" }, "attendeePhone": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "meetLink": { "type": [ "string", "null" ], "description": "The video call link the attendee got in the invitation." }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the meeting was canceled. null if it was not." }, "cancelReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "agendaId", "status", "start", "end", "durationMinutes", "timezone", "attendeeEmail", "attendeeName", "attendeePhone", "companyName", "context", "meetLink", "canceledAt", "cancelReason", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:write" ] } ], "summary": "Book a meeting", "tags": [ "Scheduling" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "scheduling:write" ] }, "get": { "description": "The meetings booked in the agendas of the organization, whoever booked them: this API, the dashboard or an agent. Newest booked first. Filter by agendaId, status, attendeeEmail or the range of start. Read only and safe to repeat. It carries the name, email and phone of the attendees, so it needs scheduling:read, which also reads the free slots.\n\nRequired scope: `scheduling:read`.", "operationId": "scheduling.meetings.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "agendaId", "required": false, "in": "query", "schema": { "example": "agd_5RvP2aKq9XwLmN3tYbZc01", "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ] } }, { "name": "attendeeEmail", "required": false, "in": "query", "description": "Only the meetings booked for this address.", "schema": { "example": "ana@empresa.cl", "type": "string" } }, { "name": "startsFrom", "required": false, "in": "query", "description": "Only meetings that start at or after this instant.", "schema": { "format": "date-time", "type": "string" } }, { "name": "startsTo", "required": false, "in": "query", "description": "Only meetings that start before this instant.", "schema": { "format": "date-time", "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:read" ] } ], "summary": "List meetings", "tags": [ "Scheduling" ], "x-lelemon-effect": "read", "x-required-scopes": [ "scheduling:read" ] } }, "/v2/scheduling/meetings/{id}": { "get": { "description": "The meeting with its status, start, attendee and video call link. Read only and safe to repeat.\n\nRequired scope: `scheduling:read`.", "operationId": "scheduling.meetings.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the meeting (mtg_…).", "schema": { "type": "string", "pattern": "^mtg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:read" ] } ], "summary": "Retrieve a meeting", "tags": [ "Scheduling" ], "x-lelemon-effect": "read", "x-required-scopes": [ "scheduling:read" ] } }, "/v2/scheduling/meetings/{id}/cancel": { "post": { "description": "Deletes the event from the calendar, which tells the attendee, and frees the slot. The meeting stays readable with status canceled. It cannot be undone: book again if it was a mistake. 409 meeting_not_active if the meeting is already canceled or finished. The reason is stored with the meeting.\n\nRequired scope: `scheduling:write`.", "operationId": "scheduling.meetings.cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the meeting (mtg_…).", "schema": { "type": "string", "pattern": "^mtg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelMeeting" }, "example": { "reason": "The customer cannot attend." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Meeting" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:write" ] } ], "summary": "Cancel a meeting", "tags": [ "Scheduling" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "scheduling:write" ] } }, "/v2/scheduling/meetings/{id}/reschedule": { "post": { "description": "Moves the same meeting, with the same person assigned, to the new start and updates the calendar event, which tells the attendee. start must be a free slot of the agenda and the person assigned must be free then: 409 slot_not_available otherwise. 409 meeting_not_active if the meeting is canceled or finished. Use dryRun=true to run the same checks and get the meeting as it would end, moving nothing.\n\nRequired scope: `scheduling:write`.", "operationId": "scheduling.meetings.reschedule", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the meeting (mtg_…).", "schema": { "type": "string", "pattern": "^mtg_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RescheduleMeeting" }, "example": { "start": "2026-11-04T15:00:00.000Z" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "example": "mtg_5RvP2aKq9XwLmN3tYbZc01" }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ], "description": "scheduled is a booked meeting. canceled is closed and frees the slot." }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "number", "example": 30 }, "timezone": { "type": "string", "example": "America/Santiago" }, "attendeeEmail": { "type": "string", "example": "ana@empresa.cl" }, "attendeeName": { "type": "string", "example": "Ana Pérez" }, "attendeePhone": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "meetLink": { "type": [ "string", "null" ], "description": "The video call link the attendee got in the invitation." }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the meeting was canceled. null if it was not." }, "cancelReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "agendaId", "status", "start", "end", "durationMinutes", "timezone", "attendeeEmail", "attendeeName", "attendeePhone", "companyName", "context", "meetLink", "canceledAt", "cancelReason", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "scheduling:write" ] } ], "summary": "Move a meeting to another slot", "tags": [ "Scheduling" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "scheduling:write" ] } }, "/v2/webhook-endpoints": { "post": { "description": "Registers a URL that receives events. The response is the only time the signing secret is shown. An organization can have up to 16 webhook endpoints; the next one answers 422 webhook_endpoint_limit.\n\nRequired scope: `webhooks:write`.", "operationId": "webhookEndpoints.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpoint" }, "example": { "url": "https://example.com/lelemon/webhooks", "enabledEvents": [ "message.received", "run.completed" ], "description": "Production receiver", "scope": "self" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:write" ] } ], "summary": "Create a webhook endpoint", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "write", "x-required-scopes": [ "webhooks:write" ], "x-lelemon-returns-secret": true }, "get": { "description": "Lists the webhook endpoints of the organization with their status and subscribed events. Secrets are never returned. Read only. It is safe to repeat.\n\nRequired scope: `webhooks:read`.", "operationId": "webhookEndpoints.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:read" ] } ], "summary": "List webhook endpoints", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "read", "x-required-scopes": [ "webhooks:read" ] } }, "/v2/webhook-endpoints/{id}": { "get": { "description": "Returns one webhook endpoint by id. Use it to refresh a single record you already know; to find records, use the list route. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `webhooks:read`.", "operationId": "webhookEndpoints.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook endpoint (whk_…).", "schema": { "type": "string", "pattern": "^whk_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:read" ] } ], "summary": "Retrieve a webhook endpoint", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "read", "x-required-scopes": [ "webhooks:read" ] }, "patch": { "description": "Change the url, the events, the scope or the description. Send `status: \"enabled\"` to turn on an endpoint the system disabled.\n\nRequired scope: `webhooks:write`.", "operationId": "webhookEndpoints.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook endpoint (whk_…).", "schema": { "type": "string", "pattern": "^whk_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpoint" }, "example": { "enabledEvents": [ "*" ], "status": "enabled" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:write" ] } ], "summary": "Update a webhook endpoint", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "write", "x-required-scopes": [ "webhooks:write" ] }, "delete": { "description": "Disables and removes a webhook endpoint. Events stop being sent to it right away. Deliveries already queued are not sent. The effect is permanent through the API. Repeating the call returns 404 not_found, because the endpoint no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `webhooks:write`.", "operationId": "webhookEndpoints.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook endpoint (whk_…).", "schema": { "type": "string", "pattern": "^whk_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:write" ] } ], "summary": "Delete a webhook endpoint", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "webhooks:write" ] } }, "/v2/webhook-endpoints/{id}/rotate-secret": { "post": { "description": "Returns a new secret. For 24 hours every event is signed with both: `Lelemon-Signature` carries two `v1` values, so you can deploy the new secret without losing events. Every call rotates again and is not idempotent. Use dryRun=true to check the endpoint and see when the previous secret would stop working; nothing changes and the answer has no secret.\n\nRequired scope: `webhooks:write`.", "operationId": "webhookEndpoints.rotateSecret", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook endpoint (whk_…).", "schema": { "type": "string", "pattern": "^whk_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabledEvents": { "type": "array", "items": { "type": "string" } }, "apiVersion": { "type": "string", "example": "2026-10-29" }, "scope": { "type": "string", "enum": [ "self", "customers" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ], "description": "Why the system turned the endpoint off, when it did." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "example": "whsec_…", "description": "The new signing secret. It is shown only here; keep it. Verify with `Lelemon-Signature`. Absent in a dryRun, which rotates nothing." }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "description": "Until when the previous secret still signs. Both signatures go in the header." }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "url", "description", "enabledEvents", "apiVersion", "scope", "status", "disabledReason", "createdAt", "updatedAt", "previousSecretExpiresAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:write" ] } ], "summary": "Rotate the signing secret", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "webhooks:write" ], "x-lelemon-returns-secret": true } }, "/v2/webhook-endpoints/{id}/test": { "post": { "description": "Sends a `webhook_endpoint.test` event, signed like any other, to this endpoint only.\n\nRequired scope: `webhooks:write`.", "operationId": "webhookEndpoints.test", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook endpoint (whk_…).", "schema": { "type": "string", "pattern": "^whk_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:write" ] } ], "summary": "Send a test event", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "webhooks:write" ] } }, "/v2/webhook-endpoints/{id}/deliveries": { "get": { "description": "One row per attempt, newest first. Attempts are kept for 30 days.\n\nRequired scope: `webhooks:read`.", "operationId": "webhookEndpoints.listDeliveries", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the webhook endpoint (whk_…).", "schema": { "type": "string", "pattern": "^whk_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "succeeded", "failed", "exhausted" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:read" ] } ], "summary": "List the deliveries of an endpoint", "tags": [ "Webhook endpoints" ], "x-lelemon-effect": "read", "x-required-scopes": [ "webhooks:read" ] } }, "/v2/events/{id}/resend": { "post": { "description": "Sends the same event again to one endpoint, or to every enabled endpoint subscribed to it. The event keeps its id; each attempt has a new `Lelemon-Delivery-Id`. Events are kept for 30 days; an older event answers 404.\n\nRequired scope: `webhooks:write`.", "operationId": "events.resend", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the event (evt_…).", "schema": { "type": "string", "pattern": "^evt_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResendEvent" }, "example": { "endpointId": "whk_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:write" ] } ], "summary": "Resend an event", "tags": [ "Events" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "webhooks:write" ] } }, "/v2/event-types": { "get": { "description": "Every event type with the JSON Schema of its `data`.\n\nRequired scope: `webhooks:read`.", "operationId": "eventTypes.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventTypeList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "webhooks:read" ] } ], "summary": "List the event types", "tags": [ "Events" ], "x-lelemon-effect": "read", "x-required-scopes": [ "webhooks:read" ] } }, "/v2/recipient-allowlist": { "get": { "description": "The closed list of people your agents may write to. Off by default: with no list, agents write to anyone.\n\nRequired scope: `recipient-allowlist:read`.", "operationId": "recipientAllowlist.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecipientAllowlist" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "recipient-allowlist:read" ] } ], "summary": "Get the recipient allowlist", "tags": [ "Recipient allowlist" ], "x-lelemon-effect": "read", "x-required-scopes": [ "recipient-allowlist:read" ] }, "put": { "description": "While enabled, a message, template, contact event, campaign or agent reply to anyone outside the list is rejected with 422 recipient_not_allowed (a campaign recipient or a trigger is skipped with not_allowed instead). It applies to the organization or subaccount the key acts on. It replaces the whole list, so a wrong call locks people out: send ?dryRun=true first to validate the entries and see the list that would result without saving it. Idempotent: the same body leaves the same list.\n\nRequired scope: `recipient-allowlist:write`.", "operationId": "recipientAllowlist.replace", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceRecipientAllowlist" }, "example": { "enabled": true, "entries": [ "+56912345678", "ana@empresa.cl", "@empresa.cl" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "recipient_allowlist" ] }, "enabled": { "type": "boolean", "description": "While true, nothing is sent to anyone who is not in entries. While false, the list is kept but ignored." }, "entries": { "example": [ "+56912345678", "ana@empresa.cl", "@empresa.cl" ], "description": "Phones in E.164, emails, or whole domains written as @domain. A domain does not include its subdomains.", "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dryRun": { "type": "boolean", "description": "Present and true only on a dry run: the list shown is what would be saved, and nothing was saved.", "const": true } }, "required": [ "object", "enabled", "entries", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "recipient-allowlist:write" ] } ], "summary": "Replace the recipient allowlist", "tags": [ "Recipient allowlist" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "recipient-allowlist:write" ] } }, "/v2/whatsapp/templates": { "post": { "description": "Sends it to WhatsApp review (in_review). You get template.status_changed when WhatsApp decides. Marketing templates always get an opt-out button, written in the language of the template (\"No recibir más\" in Spanish, \"Stop messages\" by default). To word it yourself, send a quick_reply with payload lelemon_stop_messages and your text. A template can have a document header: send header.exampleUrl, and the document itself when you send the message. Use buttons for quick replies (the tap comes back as a message with reply {id, title}, so a reminder can offer Confirm and Cancel) and for fixed links (type url, https, no variables yet). It is not idempotent: repeating it with the same name and language is a 409.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.templates.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplate" }, "examples": { "allNumbers": { "summary": "allNumbers", "value": { "name": "we_miss_you", "language": "es", "category": "marketing", "body": "Hola {{name}}, usa el código {{coupon}}.", "footer": "Responde STOP para no recibir más.", "buttons": [ { "type": "quick_reply", "text": "Quiero mi cupón" } ], "examples": { "name": "Ana", "coupon": "VUELVE10" }, "phoneNumberIds": "all" } }, "someNumbers": { "summary": "someNumbers", "value": { "name": "order_ready", "language": "es", "category": "utility", "body": "Hola {{name}}, tu pedido está listo.", "examples": { "name": "Ana" }, "phoneNumberIds": [ "pn_02y0e5MANqacVbmtn1YyeJ" ] } } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Create a template", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] }, "get": { "description": "Newest first. Filter by status.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.templates.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "in_review", "approved", "rejected", "paused" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "List templates", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/whatsapp/templates/sync": { "post": { "description": "Asks WhatsApp for the current status of your templates and updates them. WhatsApp does not notify changes, so this also runs by itself while a template is in review.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.templates.sync", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateSync" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Sync template statuses", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/whatsapp/templates/{id}": { "get": { "description": "Returns one WhatsApp template by id. Use it to refresh a single record you already know; to find records, use the list route. It includes its review status. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.templates.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the template (tpl_…).", "schema": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Retrieve a template", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] }, "patch": { "description": "WhatsApp does not allow changing the text of an approved template. Here you can only change which numbers can send it.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.templates.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the template (tpl_…).", "schema": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplate" }, "examples": { "allNumbers": { "summary": "allNumbers", "value": { "phoneNumberIds": "all" } }, "someNumbers": { "summary": "someNumbers", "value": { "phoneNumberIds": [ "pn_02y0e5MANqacVbmtn1YyeJ" ] } } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Update a template", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] }, "delete": { "description": "Also deletes it on WhatsApp. Answers 409 resource_in_use while a trigger or an active campaign uses it.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.templates.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the template (tpl_…).", "schema": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Delete a template", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/whatsapp/templates/{id}/render": { "post": { "description": "The final text with your variables, without sending.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.templates.render", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the template (tpl_…).", "schema": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RenderTemplate" }, "example": { "variables": { "name": "Ana", "coupon": "VUELVE10" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRender" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Render a template", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/whatsapp/templates/{id}/test": { "post": { "description": "Sends the template to one phone with the sample values it was created with, or yours. It opens no case. A phone that belongs to a contact who opted out of WhatsApp answers 422 contact_opted_out and nothing is sent. It sends a real message: use dryRun=true first, which runs the same checks (template approved, recipient allowlist, opt-out, variables, document, WhatsApp number) and answers 200 with the message as it would be created, sending nothing; its id is not saved.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.templates.test", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the template (tpl_…).", "schema": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestTemplate" }, "example": { "to": "+56987654321", "variables": { "name": "Ana", "coupon": "VUELVE10" } } } } }, "responses": { "200": { "description": "dryRun=true: the message as it would be created; nothing is sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_message" ] }, "id": { "type": "string", "example": "wam_3Dk0x8bVw1TqS9mYp3RkLd" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "sent", "delivered", "read", "failed", "skipped", "canceled" ] }, "templateId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "caseId": { "type": [ "string", "null" ] }, "sendAt": { "type": [ "string", "null" ], "format": "date-time" }, "skipReason": { "type": [ "string", "null" ], "description": "Why it was skipped: opted_out, no_phone, template_not_approved, human_in_control, cooldown, not_allowed or canceled." }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/MessageFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "status", "templateId", "contactId", "caseId", "sendAt", "skipReason", "failure", "createdAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Send a test message", "tags": [ "WhatsApp templates" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/whatsapp/messages": { "post": { "description": "Accepted, not delivered: delivery arrives later as message.status_changed or message.failed. It sends a message to a real person and cannot be undone: use dryRun=true first, which runs the same checks (template approved, variables, document, recipient allowlist, opt-out, WhatsApp number, human in control) and answers 200 with the message as it would be created, sending and saving nothing; its id is not saved. It checks opt-outs first: a contact that opted out answers 202 with status skipped and skipReason opted_out. With sendAt it is scheduled and can be canceled until it goes out. onReply.instructions is the context the agent gets if the contact answers.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.messages.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWhatsappMessage" }, "examples": { "toContact": { "summary": "toContact", "value": { "to": { "contactId": "ctc_02y0e5MANqacVbmtn1YyeJ" }, "templateId": "tpl_02y0e5MANqacVbmtn1YyeJ", "variables": { "name": "Ana", "coupon": "VUELVE10" } } }, "toExternalRef": { "summary": "toExternalRef", "value": { "to": { "externalRef": "crm-4471" }, "templateId": "tpl_02y0e5MANqacVbmtn1YyeJ", "variables": { "name": "Ana", "coupon": "VUELVE10" }, "sendAt": "2026-11-03T13:00:00.000Z" } }, "toPhone": { "summary": "toPhone", "value": { "to": { "phone": "+56912345678" }, "templateId": "tpl_02y0e5MANqacVbmtn1YyeJ", "variables": { "name": "Ana", "coupon": "VUELVE10" }, "from": "pn_02y0e5MANqacVbmtn1YyeJ" } } } } } }, "responses": { "200": { "description": "dryRun=true: the message as it would be created; nothing is sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_message" ] }, "id": { "type": "string", "example": "wam_3Dk0x8bVw1TqS9mYp3RkLd" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "sent", "delivered", "read", "failed", "skipped", "canceled" ] }, "templateId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "caseId": { "type": [ "string", "null" ] }, "sendAt": { "type": [ "string", "null" ], "format": "date-time" }, "skipReason": { "type": [ "string", "null" ], "description": "Why it was skipped: opted_out, no_phone, template_not_approved, human_in_control, cooldown, not_allowed or canceled." }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/MessageFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "status", "templateId", "contactId", "caseId", "sendAt", "skipReason", "failure", "createdAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Send a template", "tags": [ "WhatsApp messages" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/whatsapp/messages/{id}": { "get": { "description": "status: queued, scheduled, sent, delivered, read, failed (with failure.code from WhatsApp), skipped (with skipReason) or canceled.\n\nRequired scope: `whatsapp:read`.", "operationId": "whatsapp.messages.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the whatsapp message (wam_…).", "schema": { "type": "string", "pattern": "^wam_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Retrieve a template message", "tags": [ "WhatsApp messages" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/whatsapp/messages/{id}/cancel": { "post": { "description": "Only a message that has not gone out yet. One already sent answers 409.\n\nRequired scope: `whatsapp:write`.", "operationId": "whatsapp.messages.cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the whatsapp message (wam_…).", "schema": { "type": "string", "pattern": "^wam_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsappMessage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Cancel a scheduled message", "tags": [ "WhatsApp messages" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/contact-events": { "post": { "description": "Something happened to a contact in your system. The triggers that listen to this type send their template. Answers 201 with what was sent, or 202 with a reason: no_trigger, opted_out, no_phone, template_not_approved, human_in_control or cooldown. If the contact answers, the agent continues with the data of the event and the instructions in context. onReply.instructions replaces the fixed instructions of the trigger for this event. A trigger with onEvent also opens or moves the case right away, reported in caseActions. A trigger with cadence sends its first attempt now and the rest later, each one reported by the trigger.attempted webhook event; reporting the same event again while the cadence runs answers 202 cadence_active. Use it when something happened to a contact; do not use it to send a one-off message (use POST /v2/whatsapp/messages). Send an Idempotency-Key so a retry of the same request does not report the event twice. Use dryRun=true first: it runs the same checks (contact, onReply, triggers that match, template, variables, allowlist, opt-out, cooldown, cadence, case actions) and answers 200 with what would be sent or why not, without creating the contact, the event, cases or messages; ids in it are not saved.\n\nRequired scope: `events:write`.", "operationId": "contactEvents.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactEvent" }, "example": { "type": "customer.inactive_30_days", "contact": { "externalRef": "crm-4471", "name": "Ana Pérez" }, "data": { "lastOrder": "ORD-1042" } } } } }, "responses": { "200": { "description": "dryRun=true: what the event would do; nothing is sent or saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "contact_event" ] }, "id": { "type": "string", "example": "cev_02y0e5MANqacVbmtn1YyeJ" }, "type": { "type": "string" }, "contactId": { "type": "string" }, "result": { "type": "string", "enum": [ "sent", "skipped" ] }, "sent": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEventSent" } }, "caseActions": { "description": "What each matching trigger with onEvent did to the case of the contact: opened a new case, moved the open one, left it where it was (unchanged), or found no open case to move (none). Empty when no trigger has onEvent.", "type": "array", "items": { "$ref": "#/components/schemas/ContactEventCaseAction" } }, "reason": { "type": [ "string", "null" ], "description": "Why nothing was sent: null when the matching triggers only act on the case and have no message, no_trigger, opted_out, no_phone, template_not_approved, human_in_control, cooldown, no_whatsapp_number, not_allowed or missing_variable. Cadence triggers add cadence_active (the contact is already in this cadence) and outside_window (the first attempt waits for the next window). Email triggers add no_email, recipient_not_allowed, no_verified_domain and open_case_elsewhere." }, "createdAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "type", "contactId", "result", "sent", "caseActions", "reason", "createdAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEvent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "events:write" ] } ], "summary": "Report a contact event", "tags": [ "Contact events" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "events:write" ] } }, "/v2/contact-events/{id}": { "get": { "description": "Which triggers matched, what was sent, or why nothing was.\n\nRequired scope: `triggers:read`.", "operationId": "contactEvents.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the contact event (cev_…).", "schema": { "type": "string", "pattern": "^cev_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEvent" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:read" ] } ], "summary": "Retrieve a contact event", "tags": [ "Contact events" ], "x-lelemon-effect": "read", "x-required-scopes": [ "triggers:read" ] } }, "/v2/triggers": { "post": { "description": "When you report a contact event with this name, the template goes out with the variables taken from the event. variables must cover every variable of the template. Add onEvent to open or move the contact case the moment the event arrives, without waiting for a reply. Leave templateId out and send only onEvent for a trigger that sends no message: when the event arrives it opens or moves the case of the contact and nothing goes out, so it costs nothing; a trigger with neither templateId nor onEvent is rejected because it would do nothing. Add cadence to repeat the template up to 5 times until the contact replies, opts out, or the case changes stage or closes. onEvent and cadence are for WhatsApp triggers only, and a trigger without a template has no variables, onReply, instructions, cooldownDays or cadence. Creating a trigger sends nothing, and send an Idempotency-Key to make a retry safe. Use dryRun=true to run the same checks (template, variables, onReply, onEvent, cadence) and get 200 with the trigger as it would be saved, without saving it; its id is not saved.\n\nRequired scope: `triggers:write`.", "operationId": "triggers.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrigger" }, "example": { "contactEvent": "customer.inactive_30_days", "channel": "whatsapp", "templateId": "tpl_02y0e5MANqacVbmtn1YyeJ", "variables": { "name": "contact.name", "coupon": "data.coupon" }, "instructions": "The customer got a 10% coupon. Help them place an order.", "cooldownDays": 30, "cadence": { "attempts": 3, "intervalHours": 24, "window": { "from": "09:00", "to": "19:00", "timezone": "America/Santiago" }, "stopOn": [ "reply", "opt_out" ] } } } } }, "responses": { "200": { "description": "dryRun=true: the trigger as it would be saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "trigger" ] }, "id": { "type": "string", "example": "trg_1Qa0x8bVw1TqS9mYp3RkLd" }, "contactEvent": { "type": "string" }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "templateId": { "type": [ "string", "null" ] }, "email": { "anyOf": [ { "$ref": "#/components/schemas/TriggerEmail" }, { "type": "null" } ] }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "onReply": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnReply" }, { "type": "null" } ] }, "instructions": { "type": [ "string", "null" ] }, "cooldownDays": { "type": [ "integer", "null" ] }, "onEvent": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnEvent" }, { "type": "null" } ] }, "cadence": { "anyOf": [ { "$ref": "#/components/schemas/TriggerCadence" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "contactEvent", "channel", "templateId", "email", "variables", "onReply", "instructions", "cooldownDays", "onEvent", "cadence", "status", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trigger" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:write" ] } ], "summary": "Create a trigger", "tags": [ "Triggers" ], "x-lelemon-effect": "write", "x-required-scopes": [ "triggers:write" ] }, "get": { "description": "Lists the triggers of the organization: the rules that send a message when an event arrives or a contact stays silent. Filter to find one before you change it. Read only. It is safe to repeat.\n\nRequired scope: `triggers:read`.", "operationId": "triggers.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "contactEvent", "required": false, "in": "query", "description": "Only the triggers of this fact.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:read" ] } ], "summary": "List triggers", "tags": [ "Triggers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "triggers:read" ] } }, "/v2/triggers/{id}": { "get": { "description": "Returns one trigger by id. Use it to refresh a single record you already know; to find records, use the list route. It includes its cadence. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `triggers:read`.", "operationId": "triggers.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the trigger (trg_…).", "schema": { "type": "string", "pattern": "^trg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trigger" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:read" ] } ], "summary": "Retrieve a trigger", "tags": [ "Triggers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "triggers:read" ] }, "patch": { "description": "Change any field. status paused stops it without deleting it, and it also ends the cadences already running. Send onEvent or cadence as null to remove them. A change to cadence applies to new events only: cadences already running keep the settings they started with. Use dryRun=true to run the same checks and get the trigger as it would be saved, without saving it.\n\nRequired scope: `triggers:write`.", "operationId": "triggers.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the trigger (trg_…).", "schema": { "type": "string", "pattern": "^trg_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTrigger" }, "example": { "status": "paused", "cooldownDays": 15, "cadence": null } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "trigger" ] }, "id": { "type": "string", "example": "trg_1Qa0x8bVw1TqS9mYp3RkLd" }, "contactEvent": { "type": "string" }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "templateId": { "type": [ "string", "null" ] }, "email": { "anyOf": [ { "$ref": "#/components/schemas/TriggerEmail" }, { "type": "null" } ] }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "onReply": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnReply" }, { "type": "null" } ] }, "instructions": { "type": [ "string", "null" ] }, "cooldownDays": { "type": [ "integer", "null" ] }, "onEvent": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnEvent" }, { "type": "null" } ] }, "cadence": { "anyOf": [ { "$ref": "#/components/schemas/TriggerCadence" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "contactEvent", "channel", "templateId", "email", "variables", "onReply", "instructions", "cooldownDays", "onEvent", "cadence", "status", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:write" ] } ], "summary": "Update a trigger", "tags": [ "Triggers" ], "x-lelemon-effect": "write", "x-required-scopes": [ "triggers:write" ] }, "delete": { "description": "Deletes a trigger. Events that arrive afterwards no longer start it. To stop it for a while and keep it, disable it with the update route instead. The effect is permanent through the API. Repeating the call returns 404 not_found, because the trigger no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `triggers:write`.", "operationId": "triggers.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the trigger (trg_…).", "schema": { "type": "string", "pattern": "^trg_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:write" ] } ], "summary": "Delete a trigger", "tags": [ "Triggers" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "triggers:write" ] } }, "/v2/triggers/{id}/runs": { "get": { "description": "Lists the cadence runs of the trigger, newest first: the contact, how many attempts went out, when the next one goes and why it stopped. A trigger without cadence has none. Read only. 404 not_found when the trigger does not exist or belongs to another organization. It is safe to repeat.\n\nRequired scope: `triggers:read`.", "operationId": "triggers.runs.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the trigger (trg_…).", "schema": { "type": "string", "pattern": "^trg_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CadenceRunList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "triggers:read" ] } ], "summary": "List the runs of a trigger", "tags": [ "Triggers" ], "x-lelemon-effect": "read", "x-required-scopes": [ "triggers:read" ] } }, "/v2/opt-outs": { "get": { "description": "Contacts that must not be written to on a channel. Newest first. source contact means they asked for it; organization means you set it.\n\nRequired scope: `contacts:read`.", "operationId": "optOuts.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "channel", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "whatsapp", "email", "voice" ] } }, { "name": "source", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "contact", "organization" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOutList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "contacts:read" ] } ], "summary": "List opt-outs", "tags": [ "Opt-outs" ], "x-lelemon-effect": "read", "x-required-scopes": [ "contacts:read" ] } }, "/v2/contacts/{contactId}/opt-outs/{channel}": { "put": { "description": "From now on nothing is sent to this contact on the channel: events, messages and campaigns skip them. Calling it again leaves the opt-out as it was.\n\nRequired scope: `opt-outs:write`.", "operationId": "contacts.optOuts.set", "parameters": [ { "name": "contactId", "required": true, "in": "path", "description": "The id of the contact (ctc_…).", "schema": { "type": "string", "pattern": "^ctc_[0-9A-Za-z]{22}$" } }, { "name": "channel", "required": true, "in": "path", "description": "The channel to opt the contact out of.", "schema": { "enum": [ "whatsapp", "email", "voice" ], "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOut" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "opt-outs:write" ] } ], "summary": "Opt a contact out", "tags": [ "Opt-outs" ], "x-lelemon-effect": "write", "x-required-scopes": [ "opt-outs:write" ] }, "delete": { "description": "Only clears opt-outs you set. One the contact asked for stays until they write again, and answers 409.\n\nRequired scope: `opt-outs:write`.", "operationId": "contacts.optOuts.clear", "parameters": [ { "name": "contactId", "required": true, "in": "path", "description": "The id of the contact (ctc_…).", "schema": { "type": "string", "pattern": "^ctc_[0-9A-Za-z]{22}$" } }, { "name": "channel", "required": true, "in": "path", "description": "The channel to clear the opt-out on.", "schema": { "enum": [ "whatsapp", "email", "voice" ], "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "opt-outs:write" ] } ], "summary": "Clear an opt-out", "tags": [ "Opt-outs" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "opt-outs:write" ] } }, "/v2/campaigns": { "post": { "description": "Starts as a draft. Nothing goes out until you launch it, and no person has to approve it. Use dryRun=true to run the same checks (audience, schedule, template, variables, onReply) and get 200 with the draft as it would be saved; nothing is saved and its id is not saved.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaign" }, "example": { "name": "Black Friday", "templateId": "tpl_02y0e5MANqacVbmtn1YyeJ", "audience": { "contactFilter": { "tags": [ "vip" ] } }, "variables": { "coupon": "BLACK20" }, "schedule": { "at": "2026-11-27T12:00:00.000Z", "window": { "from": "09:00", "to": "19:00", "timezone": "America/Santiago" }, "batchSize": 100, "batchEveryMinutes": 10 }, "onReply": { "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "instructions": "Help them use the coupon." } } } } }, "responses": { "200": { "description": "dryRun=true: the draft as it would be saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "example": "cmp_BF26" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] }, "templateId": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "components": { "description": "The components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/SendComponents" }, { "type": "null" } ] }, "document": { "description": "The document header saved on the campaign, as you sent it. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/HeaderDocument" }, { "type": "null" } ] }, "onReply": { "description": "Who continues the conversation if the contact answers, as you sent it. null when it was not set.", "anyOf": [ { "$ref": "#/components/schemas/CampaignOnReply" }, { "type": "null" } ] }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "pauseReason": { "type": [ "string", "null" ], "description": "Why it paused by itself, if it did." }, "counts": { "$ref": "#/components/schemas/CampaignCounts" }, "launchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "status", "templateId", "audience", "variables", "components", "document", "onReply", "schedule", "pauseReason", "counts", "launchedAt", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Create a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] }, "get": { "description": "Lists the campaigns of the organization, newest first. Read only. It is safe to repeat.\n\nRequired scope: `whatsapp:read`.", "operationId": "campaigns.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "List campaigns", "tags": [ "Campaigns" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/campaigns/{id}": { "get": { "description": "Returns one campaign by id. Use it to refresh a single record you already know; to find records, use the list route. It includes the counts by recipient status. Read only. 404 not_found when the id does not exist or belongs to another organization. You can repeat it safely: it has no side effects.\n\nRequired scope: `whatsapp:read`.", "operationId": "campaigns.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Retrieve a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] }, "patch": { "description": "Only a draft can be edited. Answers 409 otherwise. Use dryRun=true to run the same checks and get the campaign as it would be saved, without saving it.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCampaign" }, "example": { "name": "Black Friday 2026", "schedule": { "at": "now" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "example": "cmp_BF26" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] }, "templateId": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "components": { "description": "The components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/SendComponents" }, { "type": "null" } ] }, "document": { "description": "The document header saved on the campaign, as you sent it. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/HeaderDocument" }, { "type": "null" } ] }, "onReply": { "description": "Who continues the conversation if the contact answers, as you sent it. null when it was not set.", "anyOf": [ { "$ref": "#/components/schemas/CampaignOnReply" }, { "type": "null" } ] }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "pauseReason": { "type": [ "string", "null" ], "description": "Why it paused by itself, if it did." }, "counts": { "$ref": "#/components/schemas/CampaignCounts" }, "launchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "status", "templateId", "audience", "variables", "components", "document", "onReply", "schedule", "pauseReason", "counts", "launchedAt", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Update a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] }, "delete": { "description": "Cancel a running campaign first: answers 409 while it is scheduled, sending or paused.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Delete a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/campaigns/{id}/preview": { "post": { "description": "Who gets it, who is skipped and why, a rendered sample and the estimated cost at the list rate of the Meta rate card (never null).\n\nRequired scope: `whatsapp:read`.", "operationId": "campaigns.preview", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignPreview" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "Preview a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/campaigns/{id}/launch": { "post": { "description": "Freezes the recipient list and starts at schedule.at, in batches inside the daily window. Launching twice answers 409; a restart in the middle never sends twice to the same contact. It sends messages that cost money and cannot be undone: use dryRun=true first, which checks the template and the state and answers with the campaign in the status it would take (scheduled or sending), without freezing the list or sending anything; use POST /v2/campaigns/{id}/preview for the recipients and the cost.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.launch", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "example": "cmp_BF26" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] }, "templateId": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "components": { "description": "The components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/SendComponents" }, { "type": "null" } ] }, "document": { "description": "The document header saved on the campaign, as you sent it. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/HeaderDocument" }, { "type": "null" } ] }, "onReply": { "description": "Who continues the conversation if the contact answers, as you sent it. null when it was not set.", "anyOf": [ { "$ref": "#/components/schemas/CampaignOnReply" }, { "type": "null" } ] }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "pauseReason": { "type": [ "string", "null" ], "description": "Why it paused by itself, if it did." }, "counts": { "$ref": "#/components/schemas/CampaignCounts" }, "launchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "status", "templateId", "audience", "variables", "components", "document", "onReply", "schedule", "pauseReason", "counts", "launchedAt", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Launch a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/campaigns/{id}/pause": { "post": { "description": "Pauses a campaign that is scheduled or sending. Messages already sent are not recalled; the pending recipients wait until you resume. 409 conflict when the campaign is in any other state. Pausing a paused campaign is a 409, not a second pause.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.pause", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Pause a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "write", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/campaigns/{id}/resume": { "post": { "description": "Resumes a paused campaign and queues its pending recipients, so messages leave and cost money. A campaign whose schedule is still in the future goes back to scheduled. 409 conflict when the campaign is not paused. Use dryRun=true to check the state and see the status it would take, without queueing anything.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.resume", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "example": "cmp_BF26" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] }, "templateId": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "components": { "description": "The components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/SendComponents" }, { "type": "null" } ] }, "document": { "description": "The document header saved on the campaign, as you sent it. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/HeaderDocument" }, { "type": "null" } ] }, "onReply": { "description": "Who continues the conversation if the contact answers, as you sent it. null when it was not set.", "anyOf": [ { "$ref": "#/components/schemas/CampaignOnReply" }, { "type": "null" } ] }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "pauseReason": { "type": [ "string", "null" ], "description": "Why it paused by itself, if it did." }, "counts": { "$ref": "#/components/schemas/CampaignCounts" }, "launchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "name", "status", "templateId", "audience", "variables", "components", "document", "onReply", "schedule", "pauseReason", "counts", "launchedAt", "createdAt", "updatedAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Resume a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/campaigns/{id}/cancel": { "post": { "description": "What was not sent yet is not sent. What already went out stays.\n\nRequired scope: `whatsapp:write`.", "operationId": "campaigns.cancel", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:write" ] } ], "summary": "Cancel a campaign", "tags": [ "Campaigns" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "whatsapp:write" ] } }, "/v2/campaigns/{id}/recipients": { "get": { "description": "Lists the recipients of a campaign with the status of each one: pending, queued, sent, delivered, read, failed or skipped. Use it to see who did not receive the message and why. Read only. It is safe to repeat.\n\nRequired scope: `whatsapp:read`.", "operationId": "campaigns.recipients.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the campaign (cmp_…).", "schema": { "type": "string", "pattern": "^cmp_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "name": "status", "required": false, "in": "query", "schema": { "type": "string", "enum": [ "pending", "queued", "sent", "delivered", "read", "failed", "skipped" ] } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignRecipientList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "whatsapp:read" ] } ], "summary": "List recipients", "tags": [ "Campaigns" ], "x-lelemon-effect": "read", "x-required-scopes": [ "whatsapp:read" ] } }, "/v2/email/domains": { "post": { "description": "Returns the DNS records to add at your DNS host. Until the domain is verified nothing can be sent from it.\n\nRequired scope: `email:write`.", "operationId": "email.domains.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailDomain" }, "example": { "name": "mail.acme.com", "defaultFromLocal": "hello", "inboundAgentId": "agt_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:write" ] } ], "summary": "Add a sender domain", "tags": [ "Email domains" ], "x-lelemon-effect": "write", "x-required-scopes": [ "email:write" ] }, "get": { "description": "Lists the sender domains of the organization with their verification status and DNS records. Read only. It is safe to repeat.\n\nRequired scope: `email:read`.", "operationId": "email.domains.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomainList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:read" ] } ], "summary": "List the sender domains", "tags": [ "Email domains" ], "x-lelemon-effect": "read", "x-required-scopes": [ "email:read" ] } }, "/v2/email/domains/{id}": { "get": { "description": "While the domain is pending, the status is refreshed from the email provider.\n\nRequired scope: `email:read`.", "operationId": "email.domains.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the email domain (dom_…).", "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:read" ] } ], "summary": "Get a sender domain with its status and DNS records", "tags": [ "Email domains" ], "x-lelemon-effect": "read", "x-required-scopes": [ "email:read" ] }, "patch": { "description": "Changes the default sender address or the agent that answers inbound mail on a domain. Send only the fields you want to change. Applying the same body twice leaves the same result.\n\nRequired scope: `email:write`.", "operationId": "email.domains.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the email domain (dom_…).", "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEmailDomain" }, "example": { "defaultFromLocal": "support" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:write" ] } ], "summary": "Change the default sender or the inbound agent of a domain", "tags": [ "Email domains" ], "x-lelemon-effect": "write", "x-required-scopes": [ "email:write" ] }, "delete": { "description": "Removes a sender domain from the organization and, when possible, from the email provider. Mail stops going out from that domain. Add it again to start over. The effect is permanent through the API. Repeating the call returns 404 not_found, because the domain no longer exists, so do not retry a 404 as a failure.\n\nRequired scope: `email:write`.", "operationId": "email.domains.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the email domain (dom_…).", "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:write" ] } ], "summary": "Remove a sender domain", "tags": [ "Email domains" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "email:write" ] } }, "/v2/email/domains/{id}/verify": { "post": { "description": "Asks the email provider to check the DNS records now, instead of waiting for the next automatic check. Returns the domain with its updated status. Safe to repeat while you fix the records; it sends no mail.\n\nRequired scope: `email:write`.", "operationId": "email.domains.verify", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the email domain (dom_…).", "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailDomain" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:write" ] } ], "summary": "Check the DNS records now", "tags": [ "Email domains" ], "x-lelemon-effect": "write", "x-lelemon-open-world": true, "x-required-scopes": [ "email:write" ] } }, "/v2/email/messages": { "post": { "description": "Sends the email and opens a case (or reuses the open email case of the contact), so the answer comes back into that case and the agent continues. No 24 hour window. It sends an email to a real person and cannot be undone: use dryRun=true first, which runs the same checks (recipient, opt-out, allowlist, verified sender domain, open case and its destination) and answers 200 with the message as it would be created, sending and saving nothing; its id is not saved. A contact that opted out answers 202 with status skipped and skipReason opted_out. 422 sender_domain_not_verified without a verified domain. onReply.instructions is the context the agent gets if the contact answers. To send files, open the case with POST /v2/cases (channel email) and use POST /v2/cases/{id}/messages.\n\nRequired scope: `email:write`.", "operationId": "email.messages.create", "parameters": [ { "name": "dryRun", "required": false, "in": "query", "description": "When true, the request goes through the same validation as the real one and is answered with what would happen (always 200), and nothing is saved, sent or charged. The answer has the same shape as the real one plus `dryRun: true`; an id in it is not saved. It does not use the Idempotency-Key.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmailMessage" }, "examples": { "toContact": { "summary": "toContact", "value": { "to": { "contactId": "ctc_02y0e5MANqacVbmtn1YyeJ" }, "subject": "Your order is ready", "text": "Hi Ana, your order is ready to pick up.", "from": "support@mail.acme.com" } }, "toExternalRef": { "summary": "toExternalRef", "value": { "to": { "externalRef": "crm-4471" }, "subject": "Your order is ready", "text": "Hi Ana, your order is ready to pick up." } }, "toEmail": { "summary": "toEmail", "value": { "to": { "email": "ana@example.com" }, "subject": "Your order is ready", "text": "Hi Ana, your order is ready to pick up." } } } } } }, "responses": { "200": { "description": "dryRun=true: the message as it would be created; nothing is sent.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "email_message" ] }, "id": { "type": "string", "example": "eml_3Dk0x8bVw1TqS9mYp3RkLd" }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "bounced", "failed", "skipped", "received", "rejected" ] }, "caseId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "skipReason": { "type": [ "string", "null" ], "description": "Why it was skipped: opted_out, recipient_not_allowed, no_email, human_in_control, cooldown, no_verified_domain or open_case_elsewhere." }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/MessageFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } }, "required": [ "object", "id", "direction", "status", "caseId", "contactId", "subject", "from", "to", "skipReason", "failure", "createdAt" ], "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved." } } } }, "202": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:write" ] } ], "summary": "Write first by email", "tags": [ "Email messages" ], "x-lelemon-effect": "money", "x-lelemon-open-world": true, "x-required-scopes": [ "email:write" ] } }, "/v2/email/messages/{id}": { "get": { "description": "status: queued, sent, delivered, bounced, failed (with failure.code), skipped (with skipReason), received or rejected.\n\nRequired scope: `email:read`.", "operationId": "email.messages.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the email message (eml_…).", "schema": { "type": "string", "pattern": "^eml_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailMessage" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "email:read" ] } ], "summary": "Retrieve an email message", "tags": [ "Email messages" ], "x-lelemon-effect": "read", "x-required-scopes": [ "email:read" ] } }, "/v2/teams": { "get": { "description": "Every team of the organization with its members and pipelines, by name, in pages. Read only. A pipeline belongs to exactly one team.\n\nRequired scope: `teams:read`.", "operationId": "teams.list", "parameters": [ { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:read" ] } ], "summary": "List the teams", "tags": [ "Teams" ], "x-lelemon-effect": "read", "x-required-scopes": [ "teams:read" ] }, "post": { "description": "Creates an empty team, and moves into it the pipelines you list. Add members with PUT /v2/teams/{id}/members/{memberId}.\n\nRequired scope: `teams:write`.", "operationId": "teams.create", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeam" }, "example": { "name": "Support", "pipelineIds": [ "ppl_02y0e5MANqacVbmtn1YyeJ" ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Create a team", "tags": [ "Teams" ], "x-lelemon-effect": "write", "x-required-scopes": [ "teams:write" ] } }, "/v2/teams/{id}": { "get": { "description": "Adds, for each member, whether they are available and how many chats they hold, and how many cases wait in the queue of the team pipelines.\n\nRequired scope: `teams:read`.", "operationId": "teams.retrieve", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamDetail" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:read" ] } ], "summary": "Retrieve a team", "tags": [ "Teams" ], "x-lelemon-effect": "read", "x-required-scopes": [ "teams:read" ] }, "patch": { "description": "Changes only what you send: the name and the limit of open chats per member. Setting a limit turns on the distribution of cases among the members.\n\nRequired scope: `teams:write`.", "operationId": "teams.update", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTeam" }, "example": { "name": "Support Chile", "maxChatsPerPerson": 5 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Update a team", "tags": [ "Teams" ], "x-lelemon-effect": "write", "x-required-scopes": [ "teams:write" ] }, "delete": { "description": "Only a team with no pipelines. Move its pipelines to another team first, or merge it with POST /v2/teams/{id}/merge.\n\nRequired scope: `teams:write`.", "operationId": "teams.delete", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Deleted." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Delete a team", "tags": [ "Teams" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "teams:write" ] } }, "/v2/teams/{id}/merge": { "post": { "description": "Moves the pipelines and members of sourceTeamId into this team and deletes sourceTeamId. A member in both keeps the leader and receives-cases marks of either.\n\nRequired scope: `teams:write`.", "operationId": "teams.merge", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeTeam" }, "example": { "sourceTeamId": "tem_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The Idempotency-Key was already used with a different request (idempotency_key_reused), or its first request is still running (idempotency_key_in_use).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Merge another team into this one", "tags": [ "Teams" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "teams:write" ] } }, "/v2/teams/{id}/pipelines/{pipelineId}": { "put": { "description": "A pipeline belongs to exactly one team, so it leaves the one it had. There is no removal: to take a pipeline out of a team, move it into another. Repeating the request is safe.\n\nRequired scope: `teams:write`.", "operationId": "teams.pipelines.set", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "name": "pipelineId", "required": true, "in": "path", "description": "The id of the pipeline (ppl_…).", "schema": { "type": "string", "pattern": "^ppl_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Move a pipeline into a team", "tags": [ "Teams" ], "x-lelemon-effect": "write", "x-required-scopes": [ "teams:write" ] } }, "/v2/teams/{id}/members/{memberId}": { "put": { "description": "Adds an active member of the organization, who receives cases and does not lead by default, or changes what you send for one who is already in. A viewer cannot lead. Repeating the request is safe.\n\nRequired scope: `teams:write`.", "operationId": "teams.members.set", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "name": "memberId", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTeamMember" }, "example": { "isLeader": true, "receivesCases": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Add a member to a team or change their role in it", "tags": [ "Teams" ], "x-lelemon-effect": "write", "x-required-scopes": [ "teams:write" ] }, "delete": { "description": "Takes the person out of the team only; they stay in the organization. Removing someone who is not in the team does nothing.\n\nRequired scope: `teams:write`.", "operationId": "teams.members.remove", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the team (tem_…).", "schema": { "type": "string", "pattern": "^tem_[0-9A-Za-z]{22}$" } }, { "name": "memberId", "required": true, "in": "path", "description": "The id of the member (mbr_…).", "schema": { "type": "string", "pattern": "^mbr_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "Removed." }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "teams:write" ] } ], "summary": "Remove a member from a team", "tags": [ "Teams" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "teams:write" ] } }, "/v2/integrations/linear": { "get": { "description": "The team and project that receive the issues, and the webhook URL to register in Linear. The API key and the signing secret are never returned. 404 when Linear is not connected. Read only and safe to repeat.\n\nRequired scope: `linear:read`.", "operationId": "linear.retrieve", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinearIntegration" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "linear:read" ] } ], "summary": "Get the Linear connection", "tags": [ "Linear" ], "x-lelemon-effect": "read", "x-required-scopes": [ "linear:read" ] }, "put": { "description": "Connects the Linear of your organization with a personal API key and chooses the team (and optionally the project) that receives the issues. Lelemon checks the key and the team with Linear before saving, and keeps the key encrypted. Connecting again replaces the key and the destination and keeps the webhook URL and the signing secret. Then create a webhook in Linear (Settings, API, Webhooks) with the Issues resource, the webhook URL of the answer, and send its signing secret with PATCH /v2/integrations/linear. 422 linear_rejected when Linear does not accept the key, the team or the project; 503 when Linear does not answer. Safe to repeat.\n\nRequired scope: `linear:write`.", "operationId": "linear.connect", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectLinear" }, "example": { "apiKey": "lin_api_xxxxxxxxxxxxxxxx", "team": "LEL" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinearIntegration" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "No such subaccount among the ones of this platform account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "linear:write" ] } ], "summary": "Connect Linear", "tags": [ "Linear" ], "x-lelemon-effect": "write", "x-required-scopes": [ "linear:write" ] }, "patch": { "description": "Changes only what you send: the API key, the team, the project, or the signing secret of the webhook. Saving the signing secret is what makes Lelemon accept the notifications of Linear. A new key or destination is checked with Linear first. 404 when Linear is not connected. Safe to repeat.\n\nRequired scope: `linear:write`.", "operationId": "linear.update", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLinear" }, "example": { "webhookSecret": "lin_wh_xxxxxxxxxxxxxxxx" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinearIntegration" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Valid, but a rule does not allow it.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "A provider or Lelemon is not answering. Retry with the same Idempotency-Key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "linear:write" ] } ], "summary": "Update the Linear connection", "tags": [ "Linear" ], "x-lelemon-effect": "write", "x-required-scopes": [ "linear:write" ] }, "delete": { "description": "Deletes the key, the signing secret and the destination, and stops accepting notifications. The issues already created stay in Linear and the escalations stay in the cases. Repeating the call returns 404, because there is nothing left to disconnect.\n\nRequired scope: `linear:write`.", "operationId": "linear.disconnect", "parameters": [ { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "204": { "description": "" }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "linear:write" ] } ], "summary": "Disconnect Linear", "tags": [ "Linear" ], "x-lelemon-effect": "destructive", "x-required-scopes": [ "linear:write" ] } }, "/v2/cases/{id}/escalate-to-team": { "post": { "description": "Creates an issue in the Linear of the organization with the title, the contact, the pipeline, the last messages and the link to the case. A case that already has an open escalation gets that same escalation back, never a second issue. When Linear does not answer, the escalation stays pending and Lelemon keeps trying; the case is not lost. When the team completes the issue, the case moves to answerStageId (if it is still in the stage where it was escalated), the answer is left as an internal note and the owner of the case gets a notification. The same happens by itself when a case enters a stage with config.attentionRole escalation and Linear is connected; answerStageId defaults to the stage of the pipeline with attentionRole answer. 404 when Linear is not connected. A closed case is a 409. Safe to repeat.\n\nRequired scope: `cases:write`.", "operationId": "cases.escalateToTeam", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "$ref": "#/components/parameters/LelemonSubaccount" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EscalateToTeam" }, "example": { "answerStageId": "stg_02y0e5MANqacVbmtn1YyeJ" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamEscalation" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflicts with the current state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:write" ] } ], "summary": "Escalate a case to the technical team", "tags": [ "Cases" ], "x-lelemon-effect": "write", "x-required-scopes": [ "cases:write" ] } }, "/v2/cases/{id}/team-escalations": { "get": { "description": "The escalations of the case to the technical team, newest first, with the Linear issue and the answer once the team completes it. Read only and safe to repeat.\n\nRequired scope: `cases:read`.", "operationId": "cases.teamEscalations.list", "parameters": [ { "name": "id", "required": true, "in": "path", "description": "The id of the case (cse_…).", "schema": { "type": "string", "pattern": "^cse_[0-9A-Za-z]{22}$" } }, { "name": "limit", "required": false, "in": "query", "schema": { "minimum": 1, "maximum": 100, "default": 20, "type": "integer" } }, { "name": "cursor", "required": false, "in": "query", "description": "The nextCursor of the previous page, with the same filters.", "schema": { "maxLength": 512, "type": "string" } }, { "$ref": "#/components/parameters/LelemonSubaccount" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamEscalationList" } } } }, "400": { "description": "Invalid request. `param` names the field.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing, invalid or revoked API key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "The key lacks a scope, or the organization is closed.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Does not exist, or is not yours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Too many requests. Wait Retry-After seconds.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Our side failed after the request started. The same Idempotency-Key returns this error again, so check what happened before retrying with a new key.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "api-key": [ "cases:read" ] } ], "summary": "List the escalations of a case", "tags": [ "Cases" ], "x-lelemon-effect": "read", "x-required-scopes": [ "cases:read" ] } } }, "info": { "title": "Lelemon API", "description": "Put AI agents on WhatsApp inside your own product. Guides at https://docs.lelemon.cl.", "version": "2", "contact": {} }, "tags": [], "servers": [ { "url": "https://api.lelemon.cl" } ], "components": { "securitySchemes": { "api-key": { "scheme": "bearer", "bearerFormat": "API key", "type": "http", "description": "Your API key: Authorization: Bearer lel_…" }, "connector-signature": { "type": "apiKey", "in": "header", "name": "Lelemon-Signature", "description": "HMAC signature that Lelemon puts on every call to your connector, with the signing secret of the connector. Verify it before answering." }, "webhook-signature": { "type": "apiKey", "in": "header", "name": "Lelemon-Signature", "description": "HMAC signature of the body with the secret of the webhook endpoint. Verify it before trusting the event." } }, "schemas": { "UpdateSettings": { "type": "object", "properties": {} }, "UpdateBasicInfo": { "type": "object", "properties": {} }, "UpdateCompanyProfile": { "type": "object", "properties": {} }, "UpsertAgentFact": { "type": "object", "properties": {} }, "AgendaTimeRange": { "type": "object", "properties": { "start": { "type": "string", "example": "09:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "end": { "type": "string", "example": "18:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" } }, "required": [ "start", "end" ] }, "AvailableHours": { "type": "object", "properties": { "monday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "tuesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "wednesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "thursday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "friday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "saturday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "sunday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } } } }, "CreateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "example": "https://example.com/lelemon/webhooks", "description": "Public http(s) address that receives the events.", "maxLength": 2048 }, "enabledEvents": { "example": [ "case.escalated", "message.received" ], "description": "Event types to receive, or \"*\" for all. See GET /v2/event-types.", "type": "array", "items": { "type": "string" }, "uniqueItems": true, "maxItems": 50, "minItems": 1 }, "description": { "type": "string", "maxLength": 500 }, "apiVersion": { "type": "string", "enum": [ "2026-10-29" ], "default": "2026-10-29" }, "scope": { "type": "string", "enum": [ "self", "customers" ], "default": "self", "description": "`self` receives the events of this organization. `customers` receives the events of its subaccounts." } }, "required": [ "url", "enabledEvents" ] }, "UpdateWebhookEndpoint": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2048 }, "enabledEvents": { "type": "array", "items": { "type": "string" }, "uniqueItems": true, "maxItems": 50, "minItems": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "apiVersion": { "type": "string", "enum": [ "2026-10-29" ] }, "scope": { "type": "string", "enum": [ "self", "customers" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Set `enabled` to turn on an endpoint that was disabled." } } }, "ErrorFix": { "type": "object", "properties": { "summary": { "type": "string", "example": "Send a new Idempotency-Key for a different request.", "description": "What to do, in one sentence a model can follow." }, "action": { "type": "string", "enum": [ "set", "remove", "retry", "call", "stop" ], "example": "set", "description": "`set` a parameter, `remove` one, `retry` the same request, `call` another endpoint first, or `stop` because only a person can fix it." }, "param": { "type": "string", "example": "Idempotency-Key", "description": "The header, query parameter or body field the fix is about. For invalid_request and required_fields_missing it is the field of the problem itself." }, "value": { "type": "object", "description": "The value to put in `param`, when the fix is the same for everyone." }, "endpoint": { "type": "string", "example": "GET /v2/models", "description": "The call to make first, as `METHOD /v2/path`." }, "docUrl": { "type": "string", "example": "https://docs.lelemon.cl/errors/idempotency_key_reused" } }, "required": [ "summary", "action", "docUrl" ] }, "BudgetExceededDetails": { "type": "object", "properties": { "id": { "type": "string", "example": "bgt_7Hc2LmQ0x8bVw1TqS9mYp3" }, "scope": { "type": "string", "enum": [ "organization", "subaccount", "agent", "contact" ] }, "subjectId": { "type": [ "string", "null" ], "description": "The sub_, agt_ or ctc_ id the budget covers. null for the organization." }, "limitConversations": { "type": "integer", "example": 500, "description": "Monthly limit in conversations." }, "usedConversations": { "type": "integer", "example": 500, "description": "Conversations used this month." }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the month ends and the used conversations go back to zero. Retry-After counts the seconds to this moment." } }, "required": [ "id", "scope", "subjectId", "limitConversations", "usedConversations", "resetsAt" ] }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "example": "https://docs.lelemon.cl/errors/not_found" }, "title": { "type": "string", "example": "Not found" }, "status": { "type": "integer", "example": 404 }, "code": { "type": "string", "example": "not_found", "enum": [ "invalid_request", "unknown_field", "invalid_cursor", "api_key_invalid", "unauthorized", "scope_missing", "agent_not_exposed", "forbidden", "grant_not_allowed", "organization_deleted", "subscription_canceled", "budget_exceeded", "not_found", "method_not_allowed", "conflict", "idempotency_key_reused", "idempotency_key_in_use", "agent_version_conflict", "external_ref_conflict", "actor_role_above_key", "approval_not_pending", "approval_decision_not_allowed", "review_not_available", "team_question_not_open", "slot_not_available", "meeting_not_active", "invalid_cron", "invalid_timezone", "schedule_limit_reached", "run_finished", "run_not_waiting", "case_agent_in_control", "case_message_limit_reached", "resource_in_use", "action_origin_not_allowed", "action_destination_blocked", "phone_number_in_use", "payload_too_large", "unprocessable", "agent_not_ready", "agent_channel_disabled", "case_channel_not_api", "channel_window_closed", "no_outbound_channel", "interactive_unsupported_channel", "catalog_not_connected", "message_variable_missing", "template_not_approved", "no_whatsapp_number", "template_across_accounts", "sender_domain_not_verified", "field_not_sensitive", "contact_without_email", "subject_required", "recipient_not_allowed", "contact_opted_out", "presence_not_configured", "action_variable_needs_authorization", "action_variable_in_query", "domain_in_use", "model_not_supported", "thinking_not_supported", "template_variable_missing", "mcp_server_unreachable", "linear_rejected", "required_fields_missing", "unsupported_file_type", "rate_limited", "data_connector_unavailable", "data_connector_invalid_response", "data_connector_not_ready", "data_connector_limit", "webhook_endpoint_limit", "internal_error", "service_unavailable" ] }, "detail": { "type": "string", "example": "No such agent: agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "param": { "type": "string", "example": "name" }, "docUrl": { "type": "string", "example": "https://docs.lelemon.cl/errors/not_found" }, "fix": { "description": "The next step for this error code. It comes from the error catalog and never repeats what you sent.", "type": "object", "properties": { "summary": { "type": "string", "example": "Send a new Idempotency-Key for a different request.", "description": "What to do, in one sentence a model can follow." }, "action": { "type": "string", "enum": [ "set", "remove", "retry", "call", "stop" ], "example": "set", "description": "`set` a parameter, `remove` one, `retry` the same request, `call` another endpoint first, or `stop` because only a person can fix it." }, "param": { "type": "string", "example": "Idempotency-Key", "description": "The header, query parameter or body field the fix is about. For invalid_request and required_fields_missing it is the field of the problem itself." }, "value": { "type": "object", "description": "The value to put in `param`, when the fix is the same for everyone." }, "endpoint": { "type": "string", "example": "GET /v2/models", "description": "The call to make first, as `METHOD /v2/path`." }, "docUrl": { "type": "string", "example": "https://docs.lelemon.cl/errors/idempotency_key_reused" } }, "required": [ "summary", "action", "docUrl" ] }, "budget": { "description": "Only with budget_exceeded: which budget stopped the agent, its limit, what was spent and when the month resets.", "type": "object", "properties": { "id": { "type": "string", "example": "bgt_7Hc2LmQ0x8bVw1TqS9mYp3" }, "scope": { "type": "string", "enum": [ "organization", "subaccount", "agent", "contact" ] }, "subjectId": { "type": [ "string", "null" ], "description": "The sub_, agt_ or ctc_ id the budget covers. null for the organization." }, "limitConversations": { "type": "integer", "example": 500, "description": "Monthly limit in conversations." }, "usedConversations": { "type": "integer", "example": 500, "description": "Conversations used this month." }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the month ends and the used conversations go back to zero. Retry-After counts the seconds to this moment." } }, "required": [ "id", "scope", "subjectId", "limitConversations", "usedConversations", "resetsAt" ] }, "requestId": { "type": "string", "example": "req_7Hc2LmQ0x8bVw1TqS9mYp3" } }, "required": [ "type", "title", "status", "code", "detail", "docUrl", "requestId" ] }, "MeOrganization": { "type": "object", "properties": { "id": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "name": { "type": "string", "example": "Mesa" }, "kind": { "type": "string", "enum": [ "organization", "subaccount" ], "description": "subaccount when the key belongs to a subaccount or acts on one with Lelemon-Subaccount." }, "platformId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The platform that owns this subaccount." } }, "required": [ "id", "name", "kind" ] }, "MeKey": { "type": "object", "properties": { "id": { "type": "string", "example": "key_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string", "example": "mesa-backend" }, "prefix": { "type": "string", "example": "lel_3Pq0a1b2c3d4" } }, "required": [ "id", "name", "prefix" ] }, "Me": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "me" ] }, "organization": { "$ref": "#/components/schemas/MeOrganization" }, "apiKey": { "$ref": "#/components/schemas/MeKey" }, "scopes": { "example": [ "agents:read", "cases:write" ], "type": "array", "items": { "type": "string" } } }, "required": [ "object", "organization", "apiKey", "scopes" ] }, "Scope": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "scope" ] }, "id": { "type": "string", "example": "agents:read" }, "description": { "type": "string", "example": "See how an agent is configured." } }, "required": [ "object", "id", "description" ] }, "ScopeList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AgentModelInput": { "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 } }, "required": [ "model" ] }, "ModelConfigInput": { "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 }, "fallback": { "description": "Answers when the main model fails.", "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 } }, "required": [ "model" ] } }, "required": [ "model" ] }, "BehaviorInput": { "type": "object", "properties": { "greeting": { "type": "string", "maxLength": 2000 }, "personality": { "type": "string", "maxLength": 2000 }, "tone": { "type": "string", "maxLength": 500 }, "displayName": { "type": "string", "maxLength": 100, "description": "The name the agent uses to introduce itself." } } }, "CreateAgent": { "anyOf": [ { "type": "object", "properties": { "audience": { "type": "string", "enum": [ "customers", "internal" ], "default": "customers", "description": "customers: the agent talks to your customers. internal: a copilot that answers your team and can use the tools of your data connector (dct_) to read your back office. Creating an internal one needs the scope agents:internal (403 scope_missing otherwise) and it cannot be made from a template. It cannot be changed later." }, "name": { "type": "string", "maxLength": 255, "description": "Required unless fromTemplate is set.", "minLength": 1 }, "fromTemplate": { "type": "string", "example": "atp_3PqA0x8bVw1TqS9mYp3RkL", "description": "A template from GET /v2/agent-templates.", "maxLength": 60 }, "description": { "type": "string", "maxLength": 1000 }, "instructions": { "type": "string", "maxLength": 200000, "description": "How the agent behaves. Required unless fromTemplate is set. May hold {{name}} placeholders.", "minLength": 1 }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values for the {{name}} placeholders in the instructions, and any fact the agent should know. Replaces the whole map. Every placeholder needs a value or the answer is 422 template_variable_missing." }, "llmConfig": { "description": "Required unless fromTemplate is set.", "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 }, "fallback": { "description": "Answers when the main model fails.", "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 } }, "required": [ "model" ] } }, "required": [ "model" ] }, "maxTokens": { "type": "integer", "minimum": 1000, "maximum": 5000000 }, "maxIterations": { "type": "integer", "minimum": 1, "maximum": 50 }, "channels": { "type": "array", "description": "Where the agent answers. An empty list means every channel.", "items": { "type": "string", "enum": [ "whatsapp", "api", "web", "email" ] } }, "behaviors": { "$ref": "#/components/schemas/BehaviorInput" }, "avatar": { "type": "string", "maxLength": 50, "minLength": 1 } }, "required": [ "fromTemplate" ], "additionalProperties": false, "example": { "fromTemplate": "atp_02y0e5MANqacVbmtn1YyeJ" } }, { "type": "object", "properties": { "audience": { "type": "string", "enum": [ "customers", "internal" ], "default": "customers", "description": "customers: the agent talks to your customers. internal: a copilot that answers your team and can use the tools of your data connector (dct_) to read your back office. Creating an internal one needs the scope agents:internal (403 scope_missing otherwise) and it cannot be made from a template. It cannot be changed later." }, "name": { "type": "string", "maxLength": 255, "description": "Required unless fromTemplate is set.", "minLength": 1 }, "fromTemplate": { "type": "string", "example": "atp_3PqA0x8bVw1TqS9mYp3RkL", "description": "A template from GET /v2/agent-templates.", "maxLength": 60 }, "description": { "type": "string", "maxLength": 1000 }, "instructions": { "type": "string", "maxLength": 200000, "description": "How the agent behaves. Required unless fromTemplate is set. May hold {{name}} placeholders.", "minLength": 1 }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values for the {{name}} placeholders in the instructions, and any fact the agent should know. Replaces the whole map. Every placeholder needs a value or the answer is 422 template_variable_missing." }, "llmConfig": { "description": "Required unless fromTemplate is set.", "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 }, "fallback": { "description": "Answers when the main model fails.", "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "Public model id from GET /v2/models. Responses return the same id.", "maxLength": 200, "minLength": 1 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "maxOutputTokens": { "type": "integer", "minimum": 1, "description": "Most tokens the model may write in one answer.", "maximum": 200000 }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ], "description": "`off` is not available on every model; the answer is 422 when it is not." }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50 } }, "required": [ "model" ] } }, "required": [ "model" ] }, "maxTokens": { "type": "integer", "minimum": 1000, "maximum": 5000000 }, "maxIterations": { "type": "integer", "minimum": 1, "maximum": 50 }, "channels": { "type": "array", "description": "Where the agent answers. An empty list means every channel.", "items": { "type": "string", "enum": [ "whatsapp", "api", "web", "email" ] } }, "behaviors": { "$ref": "#/components/schemas/BehaviorInput" }, "avatar": { "type": "string", "maxLength": 50, "minLength": 1 } }, "required": [ "name", "instructions", "llmConfig" ], "additionalProperties": false, "example": { "name": "Order bot", "instructions": "You answer questions about orders in one short sentence.", "llmConfig": { "model": "anthropic/claude-sonnet-5.5" }, "channels": [ "whatsapp" ] } } ] }, "AgentModel": { "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6" }, "temperature": { "type": "number" }, "maxOutputTokens": { "type": "integer" }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ] }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string" } } }, "required": [ "model" ] }, "ModelConfig": { "type": "object", "properties": { "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6" }, "temperature": { "type": "number" }, "maxOutputTokens": { "type": "integer" }, "effort": { "type": "string", "enum": [ "low", "medium", "high", "xhigh", "max" ] }, "thinking": { "type": "string", "enum": [ "adaptive", "off" ] }, "alwaysLoadedTools": { "type": "array", "items": { "type": "string" } }, "fallback": { "$ref": "#/components/schemas/AgentModel" } }, "required": [ "model" ] }, "Agent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string" }, "audience": { "type": "string", "enum": [ "customers", "internal" ], "description": "customers: talks to your customers. internal: a copilot for your team created with the scope agents:internal." }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "version": { "type": "integer", "description": "Goes up on every change. Send it back as expectedVersion." }, "instructions": { "type": "string", "description": "As you wrote them, with the {{name}} placeholders still in place." }, "variables": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "llmConfig": { "$ref": "#/components/schemas/ModelConfig" }, "maxTokens": { "type": "integer" }, "maxIterations": { "type": "integer" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp", "api", "web", "email" ] } }, "behaviors": { "type": "object", "additionalProperties": true }, "avatar": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "audience", "description", "status", "version", "instructions", "variables", "llmConfig", "maxTokens", "maxIterations", "channels", "behaviors", "avatar", "createdAt", "updatedAt" ] }, "AgentList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateAgent": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "type": "string", "maxLength": 1000 }, "instructions": { "type": "string", "maxLength": 200000, "description": "Creates a version. May hold {{name}} placeholders; they are filled with `variables`.", "minLength": 1 }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Values for the {{name}} placeholders in the instructions, and any fact the agent should know. Replaces the whole map. Every placeholder needs a value or the answer is 422 template_variable_missing. Creates a version." }, "llmConfig": { "$ref": "#/components/schemas/ModelConfigInput" }, "maxTokens": { "type": "integer", "minimum": 1000, "maximum": 5000000 }, "maxIterations": { "type": "integer", "minimum": 1, "maximum": 50 }, "channels": { "type": "array", "description": "Where the agent answers. An empty list means every channel.", "items": { "type": "string", "enum": [ "whatsapp", "api", "web", "email" ] } }, "behaviors": { "description": "Merged into the current behaviors, key by key.", "type": "object", "properties": { "greeting": { "type": "string", "maxLength": 2000 }, "personality": { "type": "string", "maxLength": 2000 }, "tone": { "type": "string", "maxLength": 500 }, "displayName": { "type": "string", "maxLength": 100, "description": "The name the agent uses to introduce itself." } } }, "avatar": { "type": [ "string", "null" ], "maxLength": 50, "minLength": 1 }, "expectedVersion": { "type": "integer", "minimum": 1, "description": "The version you read. If someone saved first the answer is 409 agent_version_conflict and nothing is written." } } }, "ReadinessGap": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "no_stage", "not_entry_stage", "no_api_channel" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "Readiness": { "type": "object", "properties": { "ready": { "type": "boolean", "description": "True when nothing keeps people from reaching the agent." }, "missing": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessGap" } } }, "required": [ "ready", "missing" ] }, "AgentWithReadiness": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent" ] }, "id": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string" }, "audience": { "type": "string", "enum": [ "customers", "internal" ], "description": "customers: talks to your customers. internal: a copilot for your team created with the scope agents:internal." }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "version": { "type": "integer", "description": "Goes up on every change. Send it back as expectedVersion." }, "instructions": { "type": "string", "description": "As you wrote them, with the {{name}} placeholders still in place." }, "variables": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } }, "llmConfig": { "$ref": "#/components/schemas/ModelConfig" }, "maxTokens": { "type": "integer" }, "maxIterations": { "type": "integer" }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "whatsapp", "api", "web", "email" ] } }, "behaviors": { "type": "object", "additionalProperties": true }, "avatar": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readiness": { "$ref": "#/components/schemas/Readiness" } }, "required": [ "object", "id", "name", "audience", "description", "status", "version", "instructions", "variables", "llmConfig", "maxTokens", "maxIterations", "channels", "behaviors", "avatar", "createdAt", "updatedAt", "readiness" ] }, "VersionAuthor": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "api_key", "unknown" ] }, "id": { "type": [ "string", "null" ], "example": "key_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "type", "id" ] }, "AgentVersion": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_version" ] }, "id": { "type": "string", "example": "agv_4Tn2Lm0x8bVw1TqS9mYp3R" }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "version": { "type": "integer", "description": "The agent version this one left in place." }, "author": { "$ref": "#/components/schemas/VersionAuthor" }, "chars": { "type": "integer", "description": "Length of the instructions." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "version", "author", "chars", "createdAt" ] }, "AgentVersionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentVersion" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AgentVersionWithText": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_version" ] }, "id": { "type": "string", "example": "agv_4Tn2Lm0x8bVw1TqS9mYp3R" }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "version": { "type": "integer", "description": "The agent version this one left in place." }, "author": { "$ref": "#/components/schemas/VersionAuthor" }, "chars": { "type": "integer", "description": "Length of the instructions." }, "createdAt": { "type": "string", "format": "date-time" }, "instructions": { "type": "string", "description": "The instructions as written, with placeholders in place." }, "variables": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" } } }, "required": [ "object", "id", "agentId", "version", "author", "chars", "createdAt", "instructions", "variables" ] }, "AgentFact": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_fact" ] }, "key": { "type": "string", "example": "horario" }, "value": { "type": "string", "example": "Lunes a viernes de 9 a 18" }, "source": { "type": "string", "enum": [ "manual", "auto" ], "description": "manual when someone wrote it through the API or the dashboard, auto when the agent saved it on its own." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "key", "value", "source", "createdAt", "updatedAt" ] }, "AgentFactList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentFact" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AgentTemplate": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_template" ] }, "id": { "type": "string", "example": "atp_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "variables": { "description": "The variables its instructions ask for. Send a value for each in `variables`.", "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "description", "category", "variables", "createdAt" ] }, "AgentTemplateList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTemplate" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "ModelCapabilities": { "type": "object", "properties": { "thinkingCanBeOff": { "type": "boolean", "description": "Whether thinking: off is accepted. When false, send effort low instead." }, "contextWindow": { "type": "integer", "example": 1000000 } }, "required": [ "thinkingCanBeOff", "contextWindow" ] }, "CatalogModel": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "model" ] }, "id": { "type": "string", "example": "anthropic/claude-sonnet-4.6", "description": "The value to send as llmConfig.model." }, "name": { "type": "string", "example": "Claude Sonnet 4.6" }, "capabilities": { "$ref": "#/components/schemas/ModelCapabilities" }, "deprecated": { "type": [ "string", "null" ], "example": null, "description": "Date (YYYY-MM-DD) from which the model is no longer accepted, or null." } }, "required": [ "object", "id", "name", "capabilities", "deprecated" ] }, "ModelList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogModel" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "SubaccountTemplates": { "type": "object", "properties": { "agents": { "example": [ "atp_4Zq0x8bVw1TqS9mYp3RkLd" ], "description": "Ids of the agent templates that GET /v2/agent-templates returns: Lelemon's and the ones your platform saved from the dashboard. Each one becomes a draft agent in the subaccount. A list that comes back empty means there is no template yet: leave this field out.", "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 20 }, "pipelines": { "example": [ "ppl_4Zq0x8bVw1TqS9mYp3RkLd" ], "description": "Pipelines of the platform. Each one is copied as a draft: stages and fields, never its agents, numbers, secrets or cases.", "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 10 } } }, "CreateSubaccount": { "type": "object", "properties": { "externalRef": { "type": "string", "example": "local-1042", "description": "Your own id for it. Unique among your subaccounts.", "maxLength": 255, "minLength": 1 }, "name": { "type": "string", "example": "Cafe Central", "maxLength": 255, "minLength": 1 }, "fromTemplates": { "$ref": "#/components/schemas/SubaccountTemplates" } }, "required": [ "externalRef", "name" ] }, "SubaccountCreatedResources": { "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "string" } }, "pipelines": { "type": "array", "items": { "type": "string" } } }, "required": [ "agents", "pipelines" ] }, "Subaccount": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "subaccount" ] }, "id": { "type": "string", "example": "sub_4Zq0x8bVw1TqS9mYp3RkLd" }, "externalRef": { "type": "string", "example": "local-1042" }, "name": { "type": "string", "example": "Cafe Central" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "created": { "description": "Only on create: what fromTemplates made.", "type": "object", "properties": { "agents": { "type": "array", "items": { "type": "string" } }, "pipelines": { "type": "array", "items": { "type": "string" } } }, "required": [ "agents", "pipelines" ] } }, "required": [ "object", "id", "externalRef", "name", "createdAt", "updatedAt" ] }, "SubaccountList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subaccount" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateSubaccount": { "type": "object", "properties": { "name": { "type": "string", "example": "Cafe Central Centro", "maxLength": 255, "minLength": 1 }, "externalRef": { "type": "string", "example": "local-1042", "maxLength": 255, "minLength": 1 } } }, "CreateSubaccountKey": { "type": "object", "properties": { "name": { "type": "string", "example": "Cafe Central POS", "maxLength": 120, "minLength": 1 }, "scopes": { "example": [ "agents:read" ], "description": "Scopes for the key. They cannot go beyond the ones your own key has, and never include subaccounts:* scopes.", "type": "array", "items": { "type": "string" }, "maxItems": 40 }, "authorName": { "type": "string", "description": "Accepted with cases:send, and required with conversations:send. Not allowed otherwise.", "maxLength": 100 }, "allowedActionOrigins": { "description": "Sites the key may create HTTP actions for. Only with actions:write. Up to 10, each one inside the sites of your own key. Omit it to give the key the same sites as yours.", "type": "array", "items": { "type": "string", "maxLength": 2048 }, "maxItems": 10 }, "expiresInDays": { "type": "number", "enum": [ 30, 90, 365 ] } }, "required": [ "name", "scopes" ] }, "SubaccountKey": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "api_key" ] }, "id": { "type": "string", "example": "key_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string" }, "prefix": { "type": "string", "example": "lel_1a2b3c4d5e6f" }, "scopes": { "type": "array", "items": { "type": "string" } }, "allowedActionOrigins": { "description": "The sites this key may create HTTP actions for. Empty without actions:write.", "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string", "description": "The API key itself. It is shown once and never again." } }, "required": [ "object", "id", "name", "prefix", "scopes", "allowedActionOrigins", "createdAt", "expiresAt", "secret" ] }, "ConnectionRedirects": { "type": "object", "properties": { "success": { "type": "string", "example": "https://app.example.com/whatsapp/ok", "maxLength": 2048 }, "failure": { "type": "string", "example": "https://app.example.com/whatsapp/failed", "maxLength": 2048 } } }, "CreateWhatsappConnection": { "type": "object", "properties": { "phone": { "type": "string", "example": "+56912345678", "description": "The number the subaccount will link, in E.164. If they link another one, the connection fails and nothing is attached.", "pattern": "^\\+[1-9]\\d{6,14}$" }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that will answer on this number.", "maxLength": 64, "minLength": 1 }, "connectionType": { "type": "string", "enum": [ "coexistence", "dedicated" ], "description": "coexistence keeps the WhatsApp Business app working next to the API; dedicated is API only." }, "redirects": { "$ref": "#/components/schemas/ConnectionRedirects" }, "language": { "type": "string", "enum": [ "es", "en", "pt" ], "default": "es" } }, "required": [ "phone", "agentId", "connectionType" ] }, "ConnectionFailure": { "type": "object", "properties": { "code": { "type": "string", "example": "phone_number_mismatch", "enum": [ "phone_number_mismatch", "phone_number_unverifiable", "phone_number_in_use" ] }, "message": { "type": "string", "example": "The number linked is not the one requested." } }, "required": [ "code", "message" ] }, "WhatsappConnection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_connection" ] }, "id": { "type": "string", "example": "wcn_4Zq0x8bVw1TqS9mYp3RkLd" }, "phone": { "type": "string", "example": "+56912345678" }, "agentId": { "type": [ "string", "null" ], "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "connectionType": { "type": "string", "enum": [ "coexistence", "dedicated" ] }, "status": { "type": "string", "enum": [ "pending", "connected", "failed", "revoked", "expired", "disconnected" ] }, "setupUrl": { "type": [ "string", "null" ], "description": "Send the subaccount here. Only while status is pending." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "phoneNumberId": { "type": [ "string", "null" ], "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The phone number it created, once connected." }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/ConnectionFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "phone", "agentId", "connectionType", "status", "setupUrl", "expiresAt", "phoneNumberId", "failure", "createdAt", "updatedAt" ] }, "WhatsappConnectionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WhatsappConnection" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "PhoneNumber": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "phone_number" ] }, "id": { "type": "string", "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd" }, "phone": { "type": [ "string", "null" ], "example": "+56 9 1234 5678" }, "verifiedName": { "type": [ "string", "null" ], "example": "Cafe Central" }, "label": { "type": [ "string", "null" ], "example": "Sucursal Centro", "description": "Your own name for the number, such as the branch it serves." }, "catalogId": { "type": [ "string", "null" ], "example": "1234567890", "description": "The id of the Meta catalog connected to this number. The product, product_list and catalog messages and the catalog templates only send with this catalog. null when none is set." }, "agentId": { "type": [ "string", "null" ], "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "phone", "verifiedName", "label", "catalogId", "agentId", "active", "createdAt", "updatedAt" ] }, "PhoneNumberList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PhoneNumber" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdatePhoneNumber": { "type": "object", "properties": { "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that answers on this number from now on.", "maxLength": 64, "minLength": 1 }, "active": { "type": "boolean", "description": "false stops the agent from answering; true turns it back on." }, "label": { "type": [ "string", "null" ], "maxLength": 100, "example": "Sucursal Centro", "description": "Your own name for the number, such as the branch it serves. Send null to clear it.", "minLength": 1 }, "catalogId": { "type": [ "string", "null" ], "maxLength": 100, "example": "1234567890", "description": "The id of the catalog you connected to this number in Meta Commerce Manager and WhatsApp Manager. Send null to clear it. The platform cannot ask Meta whether it exists: a wrong id shows up as a failed message with its error.", "pattern": "^[0-9]{5,100}$" } } }, "CommerceSettings": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "commerce_settings" ] }, "phoneNumberId": { "type": "string", "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd" }, "isCartEnabled": { "type": "boolean", "description": "Whether the cart button shows on the product and catalog messages. WhatsApp turns it on by default." }, "isCatalogVisible": { "type": "boolean", "description": "Whether the catalog icon shows in the chat with the number. WhatsApp turns it off by default." }, "catalogId": { "type": [ "string", "null" ], "example": "1234567890", "description": "The catalog set on the number, if any." } }, "required": [ "object", "phoneNumberId", "isCartEnabled", "isCatalogVisible", "catalogId" ] }, "UpdateCommerceSettings": { "type": "object", "properties": { "isCartEnabled": { "type": "boolean", "description": "true shows the cart button; false hides it." }, "isCatalogVisible": { "type": "boolean", "description": "true shows the catalog icon in the chat; false hides it." } } }, "ActionRequestInput": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string", "example": "https://api.mesa.cl/lelemon/orders", "description": "A public http or https URL, called exactly as written: a placeholder such as {id} is rejected with 400. It never comes back in a response, only its origin. Its site must be allowed for the API key.", "maxLength": 2000, "minLength": 1 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Header name to value. This is where your credential goes: it is stored encrypted and never comes back in a response, only the names do." }, "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 60000, "description": "Milliseconds to wait for your endpoint." } }, "required": [ "method", "url" ] }, "ActionVariableInput": { "type": "object", "properties": { "name": { "type": "string", "example": "session_id", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "description": "The name your endpoint receives: letters without accents, digits, \"_\" or \"-\", up to 64. It cannot repeat or match a property of input, ignoring case." }, "source": { "type": "string", "enum": [ "lelemon", "case_field" ], "description": "lelemon: a fact Lelemon knows, named by variable. case_field: a field of the case, named by field." }, "variable": { "type": "string", "enum": [ "case.id", "case.channel", "contact.phone", "contact.whatsapp_id", "contact.id", "contact.external_ref", "subaccount.id", "actor.id", "actor.role", "actor.declared_by", "agent.id", "organization.id" ], "example": "case.id", "description": "Required when source is lelemon, absent otherwise. See Variables of Lelemon in the actions guide for what each one sends. contact.phone and contact.whatsapp_id also need the destination authorization of the action." }, "field": { "type": "string", "example": "rut_comprador", "description": "Required when source is case_field: the key of a field the pipeline declares. If the case has no value for it, the action does not run, unless optional is true.", "maxLength": 200, "minLength": 1 }, "optional": { "type": "boolean", "default": false, "description": "Only with case_field. When true and the case has no value, the field is left out of the request instead of blocking the action." } }, "required": [ "name", "source" ] }, "ActionAuthorizationInput": { "type": "object", "properties": { "purpose": { "type": "string", "maxLength": 500, "example": "Create orders with what the customer confirms.", "description": "What the data sent to your system is used for. Article 15 bis of Law 21.719 asks the engagement to state its purpose.", "minLength": 1 }, "destinationCountry": { "type": "string", "enum": [ "chile", "outside_chile", "unknown" ], "description": "Where your system is hosted, declared by you. unknown counts as outside Chile." }, "version": { "type": "string", "example": "2026-09-1", "description": "The version of the authorization text you accept, from GET /v2/actions/authorization.", "minLength": 1 }, "confirmsTransferOutsideChile": { "type": "boolean", "description": "Required when destinationCountry is outside_chile or unknown: confirms apart that the data leaves the country (international transfer)." } }, "required": [ "purpose", "destinationCountry", "version" ] }, "CreateAction": { "type": "object", "properties": { "name": { "type": "string", "example": "create_order", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "What the agent calls it: lowercase letters, digits and underscores, starting with a letter. It cannot change later." }, "description": { "type": "string", "maxLength": 2000, "description": "When to use it. The agent reads this to decide.", "minLength": 1 }, "request": { "$ref": "#/components/schemas/ActionRequestInput" }, "input": { "type": "object", "additionalProperties": true, "description": "JSON Schema of what the agent must send: type \"object\" with properties. The agent fills it in; for GET it goes in the query, otherwise in the body.", "example": { "type": "object", "required": [ "address" ] } }, "audience": { "type": "string", "enum": [ "all", "customers" ], "default": "all", "description": "Which agents may be granted it: all, or customers (only agents that talk to the public)." }, "noPersist": { "type": "boolean", "default": false, "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "default": false, "description": "Platforms only. When true, every subaccount of yours can grant this action to its own agents. The action keeps living in your organization: calls to it are signed with your signing secret and carry the Lelemon-Subaccount-Id of the subaccount that made the call. Subaccounts cannot read, change or delete it. Turning it off, or deleting the action, removes it from the agents of your subaccounts. Its name cannot match an action that one of your subaccounts already has." }, "variables": { "maxItems": 20, "description": "Fields Lelemon fills when it makes the call, not the agent: the agent does not see them and cannot invent them. They go in the query for GET and in the body otherwise. If Lelemon does not have the value, the field is left out.", "example": [ { "name": "session_id", "source": "lelemon", "variable": "case.id" } ], "type": "array", "items": { "$ref": "#/components/schemas/ActionVariableInput" } }, "authorization": { "description": "The authorization to send personal data to your system (article 15 bis of Law 21.719): purpose, where it is hosted and the accepted text version. Optional as a block, but if you send it, send all of it. Without it the action is saved anyway, and it can be added later with PATCH.", "type": "object", "properties": { "purpose": { "type": "string", "maxLength": 500, "example": "Create orders with what the customer confirms.", "description": "What the data sent to your system is used for. Article 15 bis of Law 21.719 asks the engagement to state its purpose.", "minLength": 1 }, "destinationCountry": { "type": "string", "enum": [ "chile", "outside_chile", "unknown" ], "description": "Where your system is hosted, declared by you. unknown counts as outside Chile." }, "version": { "type": "string", "example": "2026-09-1", "description": "The version of the authorization text you accept, from GET /v2/actions/authorization.", "minLength": 1 }, "confirmsTransferOutsideChile": { "type": "boolean", "description": "Required when destinationCountry is outside_chile or unknown: confirms apart that the data leaves the country (international transfer)." } }, "required": [ "purpose", "destinationCountry", "version" ] } }, "required": [ "name", "description", "request", "input" ] }, "ActionRequest": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "origin": { "type": "string", "example": "https://api.mesa.cl", "description": "Only the origin. The path and query may hold a secret." }, "headerNames": { "description": "Names only, never the values.", "type": "array", "items": { "type": "string" } }, "timeoutMs": { "type": "integer" } }, "required": [ "method", "origin", "headerNames" ] }, "ActionVariable": { "type": "object", "properties": { "name": { "type": "string", "example": "session_id" }, "source": { "type": "string", "enum": [ "lelemon", "case_field" ] }, "variable": { "type": "string", "example": "case.id", "description": "With source lelemon. A key the catalog no longer has is ignored when the action runs." }, "field": { "type": "string", "example": "rut_comprador" }, "optional": { "type": "boolean", "description": "With case_field." } }, "required": [ "name", "source" ] }, "ActionAuthorizationRecord": { "type": "object", "properties": { "purpose": { "type": "string", "description": "What the data sent to your system is used for, as it was accepted." }, "destinationCountry": { "type": "string", "enum": [ "chile", "outside_chile", "unknown" ] }, "version": { "type": "string", "example": "2026-09-1", "description": "The version of the authorization text that was accepted." }, "acceptedAt": { "type": "string", "format": "date-time" }, "confirmedTransferOutsideChile": { "type": "boolean", "description": "True when the transfer outside Chile was confirmed apart. False when the system is in Chile." }, "dataSent": { "description": "The names of the input fields that leave for your system, never their values.", "type": "array", "items": { "type": "string" } } }, "required": [ "purpose", "destinationCountry", "version", "acceptedAt", "confirmedTransferOutsideChile", "dataSent" ] }, "Action": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action" ] }, "id": { "type": "string", "example": "act_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string", "example": "create_order" }, "description": { "type": "string" }, "request": { "$ref": "#/components/schemas/ActionRequest" }, "input": { "type": "object", "additionalProperties": true }, "audience": { "type": "string", "enum": [ "all", "customers", "internal" ] }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, every subaccount of yours can grant this action to its own agents. The action keeps living in your organization: calls to it are signed with your signing secret and carry the Lelemon-Subaccount-Id of the subaccount that made the call. Subaccounts cannot read, change or delete it. Turning it off, or deleting the action, removes it from the agents of your subaccounts. Its name cannot match an action that one of your subaccounts already has." }, "variables": { "description": "The fields Lelemon fills on every call. Empty when there are none.", "type": "array", "items": { "$ref": "#/components/schemas/ActionVariable" } }, "authorization": { "description": "The authorization in force for the destination of this action: what you accepted when you created it or last changed its destination. null when there is none, for example after the destination changed and was not authorized again, and always null on an action shared by your platform.", "anyOf": [ { "$ref": "#/components/schemas/ActionAuthorizationRecord" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "description", "request", "input", "audience", "noPersist", "sharedWithSubaccounts", "variables", "authorization", "createdAt", "updatedAt" ] }, "AuthorizationText": { "type": "object", "properties": { "version": { "type": "string", "example": "2026-09-1" }, "text": { "type": "string", "description": "The text you accept." } }, "required": [ "version", "text" ] }, "ActionAuthorization": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action_authorization" ] }, "version": { "type": "string", "example": "2026-09-1", "description": "The version to send as authorization.version." }, "text": { "type": "string", "description": "The authorization to deliver data to your system (article 15 bis of Law 21.719), which you accept every time." }, "detail": { "type": "string", "description": "What the text means in practice." }, "outsideChile": { "description": "The extra confirmation for a system outside Chile. Accept it with authorization.confirmsTransferOutsideChile.", "type": "object", "properties": { "version": { "type": "string", "example": "2026-09-1" }, "text": { "type": "string", "description": "The text you accept." } }, "required": [ "version", "text" ] }, "countries": { "type": "array", "items": { "type": "string", "enum": [ "chile", "outside_chile", "unknown" ] } } }, "required": [ "object", "version", "text", "detail", "outsideChile", "countries" ] }, "ActionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "ActionSigningSecretRotation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action_signing_secret_rotation" ] }, "rotatedAt": { "type": "string", "format": "date-time" }, "previousValidUntil": { "type": "string", "format": "date-time", "description": "Until when calls signed with the previous secret still verify. Read the new secret of each action with GET /v2/actions/{id}/signing-secret." } }, "required": [ "object", "rotatedAt", "previousValidUntil" ] }, "ActionSigningSecret": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action_signing_secret" ] }, "actionId": { "type": "string", "example": "act_4Zq0x8bVw1TqS9mYp3RkLd" }, "secrets": { "example": [ "lelsig_bX3k..." ], "description": "The secrets that sign the calls of this action, newest first. After a rotation the previous one is still listed for 24 hours: pass the whole list to verifyRequest. Each action has its own secret, derived from the one of your organization, so share it only with the system that serves that action.", "type": "array", "items": { "type": "string" } }, "previousValidUntil": { "type": "string", "format": "date-time", "description": "When the previous secret stops being listed. Absent when there is no previous secret." } }, "required": [ "object", "actionId", "secrets" ] }, "ActionRequestChange": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string", "description": "Changing the site checks it against the API key again.", "maxLength": 2000, "minLength": 1 }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Header name to value. This is where your credential goes: it is stored encrypted and never comes back in a response, only the names do. Omit to keep the current ones, send null to remove them." }, "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 60000 } } }, "UpdateAction": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 2000, "minLength": 1 }, "request": { "description": "Merged into the current request, field by field.", "type": "object", "properties": { "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE" ] }, "url": { "type": "string", "description": "Changing the site checks it against the API key again.", "maxLength": 2000, "minLength": 1 }, "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Header name to value. This is where your credential goes: it is stored encrypted and never comes back in a response, only the names do. Omit to keep the current ones, send null to remove them." }, "timeoutMs": { "type": "integer", "minimum": 1, "maximum": 60000 } } }, "input": { "type": "object", "additionalProperties": true, "description": "Replaces the whole input schema." }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, every subaccount of yours can grant this action to its own agents. The action keeps living in your organization: calls to it are signed with your signing secret and carry the Lelemon-Subaccount-Id of the subaccount that made the call. Subaccounts cannot read, change or delete it. Turning it off, or deleting the action, removes it from the agents of your subaccounts. Its name cannot match an action that one of your subaccounts already has." }, "variables": { "maxItems": 20, "description": "Replaces the whole list; omit it to keep the current one and send [] to remove them. Fields Lelemon fills when it makes the call, not the agent: the agent does not see them and cannot invent them. They go in the query for GET and in the body otherwise. If Lelemon does not have the value, the field is left out.", "example": [ { "name": "session_id", "source": "lelemon", "variable": "case.id" } ], "type": "array", "items": { "$ref": "#/components/schemas/ActionVariableInput" } }, "authorization": { "description": "Registers or renews the authorization to send data to your system. Needed again when you change the destination site or where it is hosted.", "type": "object", "properties": { "purpose": { "type": "string", "maxLength": 500, "example": "Create orders with what the customer confirms.", "description": "What the data sent to your system is used for. Article 15 bis of Law 21.719 asks the engagement to state its purpose.", "minLength": 1 }, "destinationCountry": { "type": "string", "enum": [ "chile", "outside_chile", "unknown" ], "description": "Where your system is hosted, declared by you. unknown counts as outside Chile." }, "version": { "type": "string", "example": "2026-09-1", "description": "The version of the authorization text you accept, from GET /v2/actions/authorization.", "minLength": 1 }, "confirmsTransferOutsideChile": { "type": "boolean", "description": "Required when destinationCountry is outside_chile or unknown: confirms apart that the data leaves the country (international transfer)." } }, "required": [ "purpose", "destinationCountry", "version" ] } } }, "TestAction": { "type": "object", "properties": { "input": { "type": "object", "additionalProperties": true, "description": "Sample input, as the agent would send it. For GET it goes in the query, otherwise in the body." } } }, "ActionTest": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action_test" ] }, "ok": { "type": "boolean", "description": "True when your endpoint answered with a 2xx status." }, "status": { "type": "integer", "description": "Absent when your endpoint did not answer." }, "durationMs": { "type": "integer" }, "body": { "type": "string", "description": "What your endpoint answered, cut at 4000 characters, with your credential hidden." }, "truncated": { "type": "boolean" }, "failure": { "type": "string", "enum": [ "timeout", "unreachable" ] } }, "required": [ "object", "ok", "durationMs", "body", "truncated" ] }, "McpAuthInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "bearer", "api_key" ], "description": "none: the server is open. bearer: sends Authorization: Bearer . api_key: sends your key in a header." }, "token": { "type": "string", "description": "Required for bearer. Stored encrypted and never returned.", "maxLength": 4000, "minLength": 1 }, "apiKey": { "type": "string", "description": "Required for api_key. Stored encrypted and never returned.", "maxLength": 4000, "minLength": 1 }, "headerName": { "type": "string", "example": "X-API-Key", "description": "For api_key: the header that carries the key.", "maxLength": 100 } }, "required": [ "type" ] }, "ConnectMcpServer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "example": "Mesa menu", "description": "How you see it. Its lowercase form prefixes every tool name the agent sees, so it cannot repeat or start like another server.", "minLength": 1 }, "url": { "type": "string", "example": "https://mcp.mesa.cl", "description": "A public http or https URL of a Streamable HTTP MCP server. It never comes back in a response, only its origin. Redirects are not followed.", "maxLength": 2048, "minLength": 1 }, "auth": { "description": "Defaults to none. OAuth servers are connected from the dashboard.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "bearer", "api_key" ], "description": "none: the server is open. bearer: sends Authorization: Bearer . api_key: sends your key in a header." }, "token": { "type": "string", "description": "Required for bearer. Stored encrypted and never returned.", "maxLength": 4000, "minLength": 1 }, "apiKey": { "type": "string", "description": "Required for api_key. Stored encrypted and never returned.", "maxLength": 4000, "minLength": 1 }, "headerName": { "type": "string", "example": "X-API-Key", "description": "For api_key: the header that carries the key.", "maxLength": 100 } }, "required": [ "type" ] }, "noPersist": { "type": "boolean", "default": false, "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "default": false, "description": "Platforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents." } }, "required": [ "name", "url" ] }, "McpTool": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mcp_tool" ] }, "id": { "type": "string", "example": "mtl_6Tn3XqLmN3tYbZc01aKq9R", "description": "The toolId to use in PUT /v2/agents/{id}/tools/{toolId}." }, "name": { "type": "string", "example": "get_menu" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true }, "readOnly": { "type": "boolean", "description": "True when the server says the tool does not change anything. Absent when it does not say." } }, "required": [ "object", "id", "name", "description", "inputSchema" ] }, "McpServerWithTools": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mcp_server" ] }, "id": { "type": "string", "example": "mcp_02y0e5MANqacVbmtn1YyeJ" }, "name": { "type": "string" }, "origin": { "type": "string", "example": "https://mcp.mesa.cl", "description": "Only the origin. The path and query may hold a secret." }, "status": { "type": "string", "enum": [ "connected", "error", "inactive" ], "description": "connected: the last discovery worked, the last tool call was answered and its tools can be granted. error: the last discovery or the last tool call failed; lastError says which. inactive: not connected." }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key", "oauth2" ] }, "toolCount": { "type": "integer" }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents." }, "sharedByPlatform": { "type": "boolean", "description": "True when your platform shares this server with you: you can grant its tools, not change it. Absent on your own servers." }, "lastError": { "type": [ "string", "null" ] }, "lastDiscoveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tools": { "description": "What the last discovery found.", "type": "array", "items": { "$ref": "#/components/schemas/McpTool" } } }, "required": [ "object", "id", "name", "origin", "status", "authType", "toolCount", "noPersist", "sharedWithSubaccounts", "lastError", "lastDiscoveryAt", "createdAt", "updatedAt", "tools" ] }, "McpServer": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mcp_server" ] }, "id": { "type": "string", "example": "mcp_02y0e5MANqacVbmtn1YyeJ" }, "name": { "type": "string" }, "origin": { "type": "string", "example": "https://mcp.mesa.cl", "description": "Only the origin. The path and query may hold a secret." }, "status": { "type": "string", "enum": [ "connected", "error", "inactive" ], "description": "connected: the last discovery worked, the last tool call was answered and its tools can be granted. error: the last discovery or the last tool call failed; lastError says which. inactive: not connected." }, "authType": { "type": "string", "enum": [ "none", "bearer", "api_key", "oauth2" ] }, "toolCount": { "type": "integer" }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents." }, "sharedByPlatform": { "type": "boolean", "description": "True when your platform shares this server with you: you can grant its tools, not change it. Absent on your own servers." }, "lastError": { "type": [ "string", "null" ] }, "lastDiscoveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "origin", "status", "authType", "toolCount", "noPersist", "sharedWithSubaccounts", "lastError", "lastDiscoveryAt", "createdAt", "updatedAt" ] }, "McpServerList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/McpServer" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "McpToolList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/McpTool" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateMcpServer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "minLength": 1 }, "url": { "type": "string", "description": "Changing it discovers the tools again.", "maxLength": 2048, "minLength": 1 }, "auth": { "description": "Replaces the credentials and discovers the tools again.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "none", "bearer", "api_key" ], "description": "none: the server is open. bearer: sends Authorization: Bearer . api_key: sends your key in a header." }, "token": { "type": "string", "description": "Required for bearer. Stored encrypted and never returned.", "maxLength": 4000, "minLength": 1 }, "apiKey": { "type": "string", "description": "Required for api_key. Stored encrypted and never returned.", "maxLength": 4000, "minLength": 1 }, "headerName": { "type": "string", "example": "X-API-Key", "description": "For api_key: the header that carries the key.", "maxLength": 100 } }, "required": [ "type" ] }, "noPersist": { "type": "boolean", "description": "When true, what this action returns lives only in the turn that called it. It is not kept in the tool memory between turns, in the execution trace, in approval requests or in run steps. The agent still uses it to answer. Consequences: the action cannot be replayed from a stored result, and a run interrupted in the middle of a round that called it fails instead of resuming. The provider (Bedrock) still receives the content as part of the prompt of that turn." }, "sharedWithSubaccounts": { "type": "boolean", "description": "Platforms only. When true, your subaccounts can grant the tools of this server to their agents but cannot change it. Turning it off, or deleting the server, removes the tools from their agents." } } }, "McpRunIdentity": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mcp_run_identity" ] }, "serverId": { "type": "string", "example": "mcp_02y0e5MANqacVbmtn1YyeJ" }, "enabled": { "type": "boolean", "description": "True when Lelemon signs every call it makes to this server. False means calls go unsigned and the server gets no verified context." }, "header": { "type": "string", "example": "x-agente-corrida" }, "audience": { "type": "string", "example": "https://mcp.mesa.cl/mcp" }, "kid": { "type": [ "string", "null" ], "description": "The `kid` of the secret that signs now. The JWT header carries it, so your server picks the right secret during a rotation." }, "secretCreatedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "object", "serverId", "enabled", "header", "audience", "kid", "secretCreatedAt" ] }, "ActivateMcpRunIdentity": { "type": "object", "properties": { "header": { "type": "string", "example": "x-agente-corrida", "description": "Header that carries the signed JWT. Lowercase letters, digits and hyphens, 3 to 64 characters, not one the server already uses for its own auth. Default x-agente-corrida.", "pattern": "^[a-z][a-z0-9-]{2,63}$" }, "audience": { "type": "string", "example": "https://mcp.mesa.cl/mcp", "description": "The `aud` claim: an https URL or an identifier without spaces, up to 200 characters. Default the URL of the server without query or fragment.", "pattern": "^\\S+$", "maxLength": 200 } } }, "McpRunIdentityWithSecret": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "mcp_run_identity" ] }, "serverId": { "type": "string", "example": "mcp_02y0e5MANqacVbmtn1YyeJ" }, "enabled": { "type": "boolean", "description": "True when Lelemon signs every call it makes to this server. False means calls go unsigned and the server gets no verified context." }, "header": { "type": "string", "example": "x-agente-corrida" }, "audience": { "type": "string", "example": "https://mcp.mesa.cl/mcp" }, "kid": { "type": [ "string", "null" ], "description": "The `kid` of the secret that signs now. The JWT header carries it, so your server picks the right secret during a rotation." }, "secretCreatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "secret": { "type": "string", "description": "HS256 secret. Shown only in the answer that creates it, never again, and absent in a dryRun. Store it now." }, "rotated": { "type": "boolean", "description": "Only in the answer to POST: true when the identity was already on and this call replaced the signing secret. The previous secret keeps verifying until the next rotation, so your server accepts both for a while." } }, "required": [ "object", "serverId", "enabled", "header", "audience", "kid", "secretCreatedAt" ] }, "DataConnectorFormat": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_format" ] }, "format": { "type": "string", "enum": [ "lelemon-connector/v1" ] }, "limits": { "type": "object", "additionalProperties": { "type": "integer" } }, "schemas": { "type": "object", "additionalProperties": true, "description": "JSON Schemas of the manifest, the account card, the account search and the view page." } }, "required": [ "object", "format", "limits", "schemas" ] }, "ValidateConnectorDocument": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "manifest", "account", "accounts_search", "view_page" ], "description": "Which document you are checking: manifest, account (the card), accounts_search (the answer to GET {base}/accounts?email=) or view_page (a page of a view)." }, "document": { "type": "object", "additionalProperties": true, "description": "The JSON document exactly as your connector serves it. It is checked and thrown away: nothing is stored and nothing is sent to your system." }, "baseUrl": { "type": "string", "example": "https://admin.example.com/lelemon", "description": "For account: the base URL of your connector. The hosts of an action link must be this host or one of allowedOrigins.", "maxLength": 2048 }, "allowedOrigins": { "description": "For account: more https origins an action link may use.", "type": "array", "items": { "type": "string", "maxLength": 2048 }, "maxItems": 10 } }, "required": [ "type", "document" ] }, "FormatProblem": { "type": "object", "properties": { "path": { "type": "string", "example": "$.sections[0].components[1].value" }, "message": { "type": "string", "example": "must be a finite number for money" } }, "required": [ "path", "message" ] }, "DataConnectorFormatValidation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_format_validation" ] }, "type": { "type": "string", "enum": [ "manifest", "account", "accounts_search", "view_page" ] }, "ok": { "type": "boolean", "description": "True when the document follows the format." }, "problems": { "description": "Every place that does not follow the format, up to 50, with its path. Values are never repeated.", "type": "array", "items": { "$ref": "#/components/schemas/FormatProblem" } } }, "required": [ "object", "type", "ok", "problems" ] }, "CreateDataConnector": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "example": "Backoffice", "description": "How you see it. Its lowercase form (up to 16 characters) prefixes the tools the copilot gets from this connector, so it cannot repeat another connector.", "minLength": 1 }, "baseUrl": { "type": "string", "example": "https://admin.example.com/lelemon", "description": "The https base URL of your connector. Lelemon calls {baseUrl}/manifest, {baseUrl}/accounts and {baseUrl}/views/{viewId}. It must be public and its site must be allowed for this key, the same list actions use. Redirects are not followed.", "maxLength": 2048, "minLength": 1 }, "allowedOrigins": { "maxItems": 5, "description": "Extra sites that an action link of your account cards may point to, besides the host of baseUrl. Each one must be allowed for this key.", "type": "array", "items": { "type": "string", "maxLength": 2048 } } }, "required": [ "name", "baseUrl" ] }, "DataConnector": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector" ] }, "id": { "type": "string", "example": "dcn_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string" }, "slug": { "type": "string", "description": "The prefix of the copilot tools of this connector, for example backoffice_account." }, "origin": { "type": "string", "description": "Only the origin of the base URL. The full URL never comes back." }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "format": { "type": "string", "enum": [ "lelemon-connector/v1" ] }, "status": { "type": "string", "enum": [ "pending", "active", "error" ], "description": "pending: created, never checked. active: the last check passed. error: the last check or the manifest failed, see lastError." }, "lastError": { "type": [ "string", "null" ], "enum": [ "unavailable", "invalid_response", "not_found", "bad_request", null ] }, "viewCount": { "type": "integer", "description": "Views in the stored manifest." }, "manifestFetchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "slug", "origin", "allowedOrigins", "format", "status", "lastError", "viewCount", "manifestFetchedAt", "createdAt", "updatedAt" ] }, "DataConnectorList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataConnector" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateDataConnector": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100, "minLength": 1 }, "baseUrl": { "type": "string", "description": "Changing it puts the connector back to pending until you call the check endpoint.", "maxLength": 2048, "minLength": 1 }, "allowedOrigins": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 2048 } } } }, "DataConnectorSigningSecret": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_signing_secret" ] }, "connectorId": { "type": "string", "example": "dcn_4Zq0x8bVw1TqS9mYp3RkLd" }, "secrets": { "description": "The secrets that sign the calls to this connector, newest first. After a rotation the previous one is listed for 24 hours. Pass the whole list to verifyRequest of the SDK with domain connector.", "type": "array", "items": { "type": "string" } }, "previousValidUntil": { "type": "string", "format": "date-time" } }, "required": [ "object", "connectorId", "secrets" ] }, "DataConnectorSigningSecretRotation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_signing_secret_rotation" ] }, "rotatedAt": { "type": "string", "format": "date-time" }, "previousValidUntil": { "type": "string", "format": "date-time" } }, "required": [ "object", "rotatedAt", "previousValidUntil" ] }, "DataConnectorCheck": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_check" ] }, "ok": { "type": "boolean" }, "problems": { "type": "array", "items": { "$ref": "#/components/schemas/FormatProblem" } }, "connector": { "$ref": "#/components/schemas/DataConnector" } }, "required": [ "object", "ok", "problems", "connector" ] }, "DataConnectorView": { "type": "object", "properties": { "id": { "type": "string", "example": "trials" }, "name": { "type": "string" }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true, "description": "JSON Schema of the filters the view accepts, as filter[name]=value." } }, "required": [ "id", "name", "description", "inputSchema" ] }, "DataConnectorManifest": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_manifest" ] }, "format": { "type": "string", "enum": [ "lelemon-connector/v1" ] }, "name": { "type": "string" }, "lookup": { "type": "object", "additionalProperties": { "type": "boolean" } }, "views": { "type": "array", "items": { "$ref": "#/components/schemas/DataConnectorView" } } }, "required": [ "object", "format", "name", "lookup", "views" ] }, "AccountSummary": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "account_summary" ] }, "id": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" } }, "required": [ "object", "id", "title" ] }, "AccountSummaryList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSummary" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AccountSection": { "type": "object", "properties": { "title": { "type": "string" }, "components": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Components of type field (value, masked, maskReason, revealable), table, badge or action (an https link opened by the person, never run by Lelemon). A masked field has value null." } }, "required": [ "title", "components" ] }, "AccountCard": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "account" ] }, "id": { "type": "string", "description": "The stable id your connector gives the account." }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "sections": { "type": "array", "items": { "$ref": "#/components/schemas/AccountSection" } } }, "required": [ "object", "id", "title", "sections" ] }, "RevealField": { "type": "object", "properties": { "fieldKey": { "type": "string", "example": "tax_id", "description": "The key of a field of the account card.", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, "required": [ "fieldKey" ] }, "RevealedField": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "revealed_field" ] }, "key": { "type": "string" }, "valueType": { "type": "string" }, "value": { "anyOf": [ { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] }, "currency": { "type": "string" } }, "required": [ "object", "key", "valueType", "value" ] }, "ActionLink": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "action_link" ] }, "url": { "type": "string", "description": "An https link inside the sites of the connector. Open it in a new tab with rel=noopener noreferrer. Lelemon never calls it." } }, "required": [ "object", "url" ] }, "ViewPage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "columns": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Columns of the view: key, label, valueType and sensitive." }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Rows with id, optional accountId and cells. Each cell is { value, masked, maskReason? }." } }, "required": [ "object", "hasMore", "nextCursor", "columns", "data" ] }, "DataConnectorAccess": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "data_connector_access" ] }, "id": { "type": "string" }, "connectorId": { "type": "string", "example": "dcn_4Zq0x8bVw1TqS9mYp3RkLd" }, "kind": { "type": "string" }, "actorType": { "type": "string", "enum": [ "api_key", "member" ] }, "actorId": { "type": "string" }, "onBehalfOf": { "type": [ "string", "null" ] }, "accountHmac": { "type": [ "string", "null" ], "description": "A keyed hash of the account id. It never holds the id or any value." }, "viewId": { "type": [ "string", "null" ] }, "fieldKey": { "type": [ "string", "null" ] }, "integrity": { "type": "string", "enum": [ "intact", "tampered" ], "description": "tampered means the row no longer matches its signature." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "connectorId", "kind", "actorType", "actorId", "onBehalfOf", "accountHmac", "viewId", "fieldKey", "integrity", "createdAt" ] }, "DataConnectorAccessList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataConnectorAccess" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateSkill": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Late order", "description": "How you see it.", "pattern": "\\S" }, "description": { "type": "string", "maxLength": 500, "description": "One line that says WHEN to load it. It is the only part of the skill that travels in the prompt, in every message, so keep it short.", "pattern": "\\S" }, "content": { "type": "string", "maxLength": 20000, "description": "The full instructions, in Markdown. The agent loads them when it is about to do that task.", "pattern": "\\S" }, "slug": { "type": "string", "maxLength": 100, "example": "late-order", "description": "The identifier the agent uses to load it. It cannot change. Defaults to the name in lowercase with hyphens. Creating again with the same slug and the same content returns the same skill; with different content it is a 409.", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, "requires": { "description": "Slugs of other skills of the same agent that the agent receives first, in full, every time it loads this one. One level only: a required skill cannot require another. Up to 5.", "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, "uniqueItems": true, "maxItems": 5 } }, "required": [ "name", "description", "content" ] }, "SkillWithContent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "skill" ] }, "id": { "type": "string", "example": "skl_2Wq9Lm3tYbZc01aKq9RvXn" }, "slug": { "type": "string", "example": "late-order" }, "name": { "type": "string" }, "description": { "type": "string" }, "requires": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "content": { "type": "string", "description": "Markdown." } }, "required": [ "object", "id", "slug", "name", "description", "requires", "createdAt", "updatedAt", "content" ] }, "Skill": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "skill" ] }, "id": { "type": "string", "example": "skl_2Wq9Lm3tYbZc01aKq9RvXn" }, "slug": { "type": "string", "example": "late-order" }, "name": { "type": "string" }, "description": { "type": "string" }, "requires": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "slug", "name", "description", "requires", "createdAt", "updatedAt" ] }, "SkillList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateSkill": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "pattern": "\\S", "minLength": 1 }, "description": { "type": "string", "maxLength": 500, "pattern": "\\S" }, "content": { "type": "string", "maxLength": 20000, "pattern": "\\S" }, "requires": { "description": "Slugs of other skills of the same agent that the agent receives first, in full, every time it loads this one. One level only: a required skill cannot require another. Up to 5.", "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, "uniqueItems": true, "maxItems": 5 } } }, "BusinessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Santiago", "description": "IANA time zone the hours are read in.", "maxLength": 64 }, "startHour": { "type": "integer", "minimum": 0, "maximum": 23, "example": 9 }, "endHour": { "type": "integer", "minimum": 1, "maximum": 24, "example": 18, "description": "First hour that is already outside. Must be after startHour." }, "activeSaturday": { "type": "boolean", "example": false }, "activeSunday": { "type": "boolean", "example": false } }, "required": [ "timezone", "startHour", "endHour", "activeSaturday", "activeSunday" ] }, "HandoffFarewell": { "type": "object", "properties": { "duringBusinessHours": { "type": "string", "maxLength": 500, "example": "Te paso con una persona del equipo. Te escribe en breve.", "description": "What the contact reads when the hand-off happens inside business hours." }, "outsideBusinessHours": { "type": "string", "maxLength": 500, "example": "Te paso con una persona del equipo. Hoy ya cerramos: te escribe mañana desde las 9.", "description": "What the contact reads when the hand-off happens outside business hours." } } }, "SystemToolConfig": { "type": "object", "properties": { "stageId": { "type": "string", "example": "stg_5RvP2aKq9XwLmN3tYbZc01", "description": "transfer_to_human only. The stage the case moves to when the agent hands it over. It wins over the pipeline setting. Ignored for a case in another pipeline, which falls back to the pipeline setting.", "pattern": "^stg_[0-9A-Za-z]{22}$" }, "businessHours": { "description": "transfer_to_human only. Picks which goodbye the contact reads. Without it the goodbye is always the one for business hours.", "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Santiago", "description": "IANA time zone the hours are read in.", "maxLength": 64 }, "startHour": { "type": "integer", "minimum": 0, "maximum": 23, "example": 9 }, "endHour": { "type": "integer", "minimum": 1, "maximum": 24, "example": 18, "description": "First hour that is already outside. Must be after startHour." }, "activeSaturday": { "type": "boolean", "example": false }, "activeSunday": { "type": "boolean", "example": false } }, "required": [ "timezone", "startHour", "endHour", "activeSaturday", "activeSunday" ] }, "farewell": { "description": "transfer_to_human only. The goodbye the tool writes. Without it the tool uses a neutral Spanish text.", "type": "object", "properties": { "duringBusinessHours": { "type": "string", "maxLength": 500, "example": "Te paso con una persona del equipo. Te escribe en breve.", "description": "What the contact reads when the hand-off happens inside business hours." }, "outsideBusinessHours": { "type": "string", "maxLength": 500, "example": "Te paso con una persona del equipo. Hoy ya cerramos: te escribe mañana desde las 9.", "description": "What the contact reads when the hand-off happens outside business hours." } } }, "fields": { "example": [ "comuna", "rut_comprador" ], "description": "save_case_data only. The keys of the fields the agent may write. Each one must be a field with source agent that is not sensitive. Without it the agent may write every field with source agent.", "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100, "minItems": 1 } } }, "Approver": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "role", "team", "member", "key", "requester" ], "description": "role: everyone with that role in the organization. team: members of a team. member: one person. key: one API key, which then decides through POST /v2/approvals/{id}/approve. requester: the member whose conversation asked for it, only when no one else is named." }, "value": { "type": "string", "example": "admin", "description": "A member role such as owner, admin or member for a role. A tem_, mbr_ or key_ id for the others. Leave it out for requester.", "maxLength": 64 } }, "required": [ "type" ] }, "ApprovalRule": { "type": "object", "properties": { "when": { "description": "When the rule applies: the same comparison or group as condition. Leave it out for a rule that applies to every call; it has to be the last one. A call whose argument is missing or has another type does not pass this rule silently: it goes to a person.", "$ref": "#/components/schemas/ApprovalCondition", "__uniqueRefKey": "#/components/schemas/ApprovalCondition__0" }, "effect": { "type": "string", "enum": [ "allow", "require_approval", "reject" ], "description": "allow: the agent runs the action, no one is asked. require_approval: a person decides first. reject: the action never runs and no one is asked; the agent tells the person it cannot be done." }, "approvers": { "description": "Only for effect require_approval. Who may decide a call that lands on this rule. Without it the approvers of the policy.", "type": "array", "items": { "$ref": "#/components/schemas/Approver" }, "maxItems": 20 }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 43200, "description": "Only for effect require_approval. Minutes to decide a call that lands on this rule. Without it the one of the policy." }, "escalateAfterMinutes": { "type": "integer", "minimum": 1, "description": "Only for effect require_approval. Minutes after which a request that landed on this rule escalates. Less than its expiresInMinutes.", "maximum": 43200 }, "customerMessage": { "type": "string", "maxLength": 500, "description": "What the agent tells the person when a call lands on this rule, for require_approval and reject. Without it the one of the policy, or a neutral Spanish text." } }, "required": [ "effect" ] }, "AccumulatedLimit": { "type": "object", "properties": { "param": { "type": "string", "example": "amount", "description": "The argument of the action that holds the amount, as a number. If a call carries no valid number there, it needs approval.", "maxLength": 200 }, "period": { "type": "string", "enum": [ "day", "week", "month" ], "description": "A rolling window: the last 24 hours, 7 days or 30 days, counted per contact." }, "limit": { "type": "number", "example": 50000, "description": "The most the agent may run without approval, adding up everything it already ran in the window for the same contact and action. A call that would pass it needs approval. This is what stops a split into many small orders.", "minimum": 0 } }, "required": [ "param", "period", "limit" ] }, "ApprovalPolicy": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "never", "always", "when", "rules" ], "description": "never: the agent runs the action without approval. always: every call waits for a person. when: only the calls that meet condition, or that pass accumulated, wait. rules: the ordered list in rules decides each call; the first rule that applies wins." }, "condition": { "description": "Only for mode when. A comparison {param, op, value} with op eq, ne, gt, gte, lt, lte, in (value is a list) or exists (no value), or a group {all: [...]} or {any: [...]}. Up to 3 levels and 10 comparisons. If the argument is missing or has another type the call needs approval. param is a path into the arguments of the action, like amount or order.total.", "$ref": "#/components/schemas/ApprovalCondition", "__uniqueRefKey": "#/components/schemas/ApprovalCondition__1" }, "rules": { "maxItems": 20, "description": "Only for mode rules. Evaluated in order for every call: the first rule whose when applies decides, and the rest are not read. A rule without when applies to every call and has to be last. If no rule applies the call runs, so end with a rule that has no when to choose the default. Use it for a hard cap (\"above X, reject\"), or for steps by amount (\"up to X a supervisor decides, above X the management\"). A platform floor and accumulated still apply on top: a rule can never run an action the floor sends to a person.", "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRule" } }, "accumulated": { "$ref": "#/components/schemas/AccumulatedLimit" }, "approvers": { "description": "Who may decide. Without it: owners and admins. A role includes the roles above it: admin also lets owners decide. An API key decides only if it is named here.", "type": "array", "items": { "$ref": "#/components/schemas/Approver" }, "maxItems": 20 }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 43200, "default": 1440, "description": "Minutes to decide. Past it the request expires, the action never runs and the agent tells the person." }, "escalateAfterMinutes": { "type": "integer", "minimum": 1, "description": "Minutes after which a pending request escalates: approval.escalated fires once. Less than expiresInMinutes.", "maximum": 43200 }, "customerMessage": { "type": "string", "maxLength": 500, "description": "What the agent tells the person while it waits. Without it a neutral Spanish text is used." }, "automatedDecision": { "type": "boolean", "description": "True when the action makes an automated decision about a person (Ley 21.719, art. 8 bis). It works with any mode. Every call leaves a record with the data it used and a reasonCode: an approval when a person decides, an automated decision (GET /v2/automated-decisions) when no one was asked or a rule rejected it. The person can ask for a human review of either." } }, "required": [ "mode" ] }, "AgentTool": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_tool" ] }, "id": { "type": "string", "example": "act_5RvP2aKq9XwLmN3tYbZc01", "description": "act_ for an action, mtl_ for an MCP tool, dct_ for a data connector tool, the tool name itself for a system tool. Use it in the path of PUT and DELETE." }, "kind": { "type": "string", "enum": [ "action", "mcp_tool", "data_connector_tool", "system" ] }, "name": { "type": "string", "example": "create_order" }, "description": { "type": "string" }, "serverId": { "type": "string", "example": "mcp_02y0e5MANqacVbmtn1YyeJ", "description": "For an MCP tool, the server it comes from." }, "sharedByPlatform": { "type": "boolean", "description": "For an action or an MCP tool: true when it belongs to your platform and is shared with your subaccounts. Absent for system tools and your own." }, "connectorId": { "type": "string", "example": "dcn_4Zq0x8bVw1TqS9mYp3RkLd", "description": "For a data connector tool (dct_), the data connector it reads. Only internal agents, such as a support copilot, can be granted them." }, "granted": { "type": "boolean", "description": "True when this agent may use it now." }, "config": { "description": "For a granted system tool, its configuration. Null when it has none. Absent for actions and MCP tools.", "anyOf": [ { "$ref": "#/components/schemas/SystemToolConfig" }, { "type": "null" } ] }, "approval": { "description": "The approval policy of an action or MCP tool for this agent. mode never when it runs without approval. Absent for system tools.", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "never", "always", "when", "rules" ], "description": "never: the agent runs the action without approval. always: every call waits for a person. when: only the calls that meet condition, or that pass accumulated, wait. rules: the ordered list in rules decides each call; the first rule that applies wins." }, "condition": { "description": "Only for mode when. A comparison {param, op, value} with op eq, ne, gt, gte, lt, lte, in (value is a list) or exists (no value), or a group {all: [...]} or {any: [...]}. Up to 3 levels and 10 comparisons. If the argument is missing or has another type the call needs approval. param is a path into the arguments of the action, like amount or order.total.", "$ref": "#/components/schemas/ApprovalCondition", "__uniqueRefKey": "#/components/schemas/ApprovalCondition__2" }, "rules": { "maxItems": 20, "description": "Only for mode rules. Evaluated in order for every call: the first rule whose when applies decides, and the rest are not read. A rule without when applies to every call and has to be last. If no rule applies the call runs, so end with a rule that has no when to choose the default. Use it for a hard cap (\"above X, reject\"), or for steps by amount (\"up to X a supervisor decides, above X the management\"). A platform floor and accumulated still apply on top: a rule can never run an action the floor sends to a person.", "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRule" } }, "accumulated": { "$ref": "#/components/schemas/AccumulatedLimit" }, "approvers": { "description": "Who may decide. Without it: owners and admins. A role includes the roles above it: admin also lets owners decide. An API key decides only if it is named here.", "type": "array", "items": { "$ref": "#/components/schemas/Approver" }, "maxItems": 20 }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 43200, "default": 1440, "description": "Minutes to decide. Past it the request expires, the action never runs and the agent tells the person." }, "escalateAfterMinutes": { "type": "integer", "minimum": 1, "description": "Minutes after which a pending request escalates: approval.escalated fires once. Less than expiresInMinutes.", "maximum": 43200 }, "customerMessage": { "type": "string", "maxLength": 500, "description": "What the agent tells the person while it waits. Without it a neutral Spanish text is used." }, "automatedDecision": { "type": "boolean", "description": "True when the action makes an automated decision about a person (Ley 21.719, art. 8 bis). It works with any mode. Every call leaves a record with the data it used and a reasonCode: an approval when a person decides, an automated decision (GET /v2/automated-decisions) when no one was asked or a rule rejected it. The person can ask for a human review of either." } }, "required": [ "mode" ] }, "approvalFloor": { "description": "The minimum approval your platform set for this shared action (PUT /v2/actions/{id}/approval-floor). It applies on top of approval: the stricter one wins, and approval cannot be mode never. Absent when there is none.", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "never", "always", "when", "rules" ], "description": "never: the agent runs the action without approval. always: every call waits for a person. when: only the calls that meet condition, or that pass accumulated, wait. rules: the ordered list in rules decides each call; the first rule that applies wins." }, "condition": { "description": "Only for mode when. A comparison {param, op, value} with op eq, ne, gt, gte, lt, lte, in (value is a list) or exists (no value), or a group {all: [...]} or {any: [...]}. Up to 3 levels and 10 comparisons. If the argument is missing or has another type the call needs approval. param is a path into the arguments of the action, like amount or order.total.", "$ref": "#/components/schemas/ApprovalCondition", "__uniqueRefKey": "#/components/schemas/ApprovalCondition__3" }, "rules": { "maxItems": 20, "description": "Only for mode rules. Evaluated in order for every call: the first rule whose when applies decides, and the rest are not read. A rule without when applies to every call and has to be last. If no rule applies the call runs, so end with a rule that has no when to choose the default. Use it for a hard cap (\"above X, reject\"), or for steps by amount (\"up to X a supervisor decides, above X the management\"). A platform floor and accumulated still apply on top: a rule can never run an action the floor sends to a person.", "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRule" } }, "accumulated": { "$ref": "#/components/schemas/AccumulatedLimit" }, "approvers": { "description": "Who may decide. Without it: owners and admins. A role includes the roles above it: admin also lets owners decide. An API key decides only if it is named here.", "type": "array", "items": { "$ref": "#/components/schemas/Approver" }, "maxItems": 20 }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 43200, "default": 1440, "description": "Minutes to decide. Past it the request expires, the action never runs and the agent tells the person." }, "escalateAfterMinutes": { "type": "integer", "minimum": 1, "description": "Minutes after which a pending request escalates: approval.escalated fires once. Less than expiresInMinutes.", "maximum": 43200 }, "customerMessage": { "type": "string", "maxLength": 500, "description": "What the agent tells the person while it waits. Without it a neutral Spanish text is used." }, "automatedDecision": { "type": "boolean", "description": "True when the action makes an automated decision about a person (Ley 21.719, art. 8 bis). It works with any mode. Every call leaves a record with the data it used and a reasonCode: an approval when a person decides, an automated decision (GET /v2/automated-decisions) when no one was asked or a rule rejected it. The person can ask for a human review of either." } }, "required": [ "mode" ] } }, "required": [ "object", "id", "kind", "name", "description", "granted" ] }, "AgentToolList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgentTool" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "GrantTool": { "type": "object", "properties": { "config": { "description": "Only for the system tools transfer_to_human and save_case_data. It replaces the stored configuration: leaving it out clears it. Actions and MCP tools take no configuration.", "type": "object", "properties": { "stageId": { "type": "string", "example": "stg_5RvP2aKq9XwLmN3tYbZc01", "description": "transfer_to_human only. The stage the case moves to when the agent hands it over. It wins over the pipeline setting. Ignored for a case in another pipeline, which falls back to the pipeline setting.", "pattern": "^stg_[0-9A-Za-z]{22}$" }, "businessHours": { "description": "transfer_to_human only. Picks which goodbye the contact reads. Without it the goodbye is always the one for business hours.", "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Santiago", "description": "IANA time zone the hours are read in.", "maxLength": 64 }, "startHour": { "type": "integer", "minimum": 0, "maximum": 23, "example": 9 }, "endHour": { "type": "integer", "minimum": 1, "maximum": 24, "example": 18, "description": "First hour that is already outside. Must be after startHour." }, "activeSaturday": { "type": "boolean", "example": false }, "activeSunday": { "type": "boolean", "example": false } }, "required": [ "timezone", "startHour", "endHour", "activeSaturday", "activeSunday" ] }, "farewell": { "description": "transfer_to_human only. The goodbye the tool writes. Without it the tool uses a neutral Spanish text.", "type": "object", "properties": { "duringBusinessHours": { "type": "string", "maxLength": 500, "example": "Te paso con una persona del equipo. Te escribe en breve.", "description": "What the contact reads when the hand-off happens inside business hours." }, "outsideBusinessHours": { "type": "string", "maxLength": 500, "example": "Te paso con una persona del equipo. Hoy ya cerramos: te escribe mañana desde las 9.", "description": "What the contact reads when the hand-off happens outside business hours." } } }, "fields": { "example": [ "comuna", "rut_comprador" ], "description": "save_case_data only. The keys of the fields the agent may write. Each one must be a field with source agent that is not sensitive. Without it the agent may write every field with source agent.", "type": "array", "items": { "type": "string", "maxLength": 100 }, "maxItems": 100, "minItems": 1 } } }, "approval": { "description": "Only for actions and MCP tools. Puts the tool behind a person: the agent proposes, a person or a named API key decides, and only an approval runs the action. Leaving it out keeps the policy the tool already has, so granting again never lifts it. To lift it, send mode never.", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "never", "always", "when", "rules" ], "description": "never: the agent runs the action without approval. always: every call waits for a person. when: only the calls that meet condition, or that pass accumulated, wait. rules: the ordered list in rules decides each call; the first rule that applies wins." }, "condition": { "description": "Only for mode when. A comparison {param, op, value} with op eq, ne, gt, gte, lt, lte, in (value is a list) or exists (no value), or a group {all: [...]} or {any: [...]}. Up to 3 levels and 10 comparisons. If the argument is missing or has another type the call needs approval. param is a path into the arguments of the action, like amount or order.total.", "$ref": "#/components/schemas/ApprovalCondition", "__uniqueRefKey": "#/components/schemas/ApprovalCondition__4" }, "rules": { "maxItems": 20, "description": "Only for mode rules. Evaluated in order for every call: the first rule whose when applies decides, and the rest are not read. A rule without when applies to every call and has to be last. If no rule applies the call runs, so end with a rule that has no when to choose the default. Use it for a hard cap (\"above X, reject\"), or for steps by amount (\"up to X a supervisor decides, above X the management\"). A platform floor and accumulated still apply on top: a rule can never run an action the floor sends to a person.", "type": "array", "items": { "$ref": "#/components/schemas/ApprovalRule" } }, "accumulated": { "$ref": "#/components/schemas/AccumulatedLimit" }, "approvers": { "description": "Who may decide. Without it: owners and admins. A role includes the roles above it: admin also lets owners decide. An API key decides only if it is named here.", "type": "array", "items": { "$ref": "#/components/schemas/Approver" }, "maxItems": 20 }, "expiresInMinutes": { "type": "integer", "minimum": 1, "maximum": 43200, "default": 1440, "description": "Minutes to decide. Past it the request expires, the action never runs and the agent tells the person." }, "escalateAfterMinutes": { "type": "integer", "minimum": 1, "description": "Minutes after which a pending request escalates: approval.escalated fires once. Less than expiresInMinutes.", "maximum": 43200 }, "customerMessage": { "type": "string", "maxLength": 500, "description": "What the agent tells the person while it waits. Without it a neutral Spanish text is used." }, "automatedDecision": { "type": "boolean", "description": "True when the action makes an automated decision about a person (Ley 21.719, art. 8 bis). It works with any mode. Every call leaves a record with the data it used and a reasonCode: an approval when a person decides, an automated decision (GET /v2/automated-decisions) when no one was asked or a rule rejected it. The person can ask for a human review of either." } }, "required": [ "mode" ] } } }, "ApprovalDecision": { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object", "description": "Who decided. A member of the organization (mbr_) or an API key (key_). When a key decides, actor is what your system declared: Lelemon stores it as declared by the key, not verified." }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] }, "Approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed", "preview" ], "description": "pending waits for a decision. approved, executing, executed and failed follow an approval: the action runs only after it. rejected, expired and canceled never run it. preview only appears in the answer of approve with dryRun=true: the approval as it is now, with the decision that would be recorded; nothing was decided or run." }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ], "example": "cse_5RvP2aKq9XwLmN3tYbZc01" }, "tool": { "type": "string", "example": "issue_refund", "description": "The name of the action or tool the agent wants to run." }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The exact arguments the action will run with if approved. Null when the tool is noPersist: those are kept encrypted and shown to nobody." }, "summary": { "type": "string", "description": "A line for a person to read. For a noPersist tool it is only the name." }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", "policy_not_required", null ], "description": "Why it needed approval: policy_always, policy_condition (the condition on its arguments held), policy_accumulated (the sum for this contact in the period passed the limit) or policy_rule (a rule of the policy asked for it: see ruleIndex)." }, "ruleIndex": { "type": [ "integer", "null" ], "description": "The position (from 0) of the rule of the policy that decided this, when reasonCode is policy_rule. Null otherwise." }, "automatedDecision": { "type": "boolean", "description": "True when the policy marks this as an automated decision about a person (Ley 21.719, art. 8 bis). The person may ask for a review." }, "dataSeen": { "description": "The names of the argument fields the approver was shown. Never their values.", "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "$ref": "#/components/schemas/Approver" } }, "requestedByKeyId": { "type": [ "string", "null" ], "description": "The API key whose turn proposed the action, if any. It can never decide this request." }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/ApprovalDecision" }, { "type": "null" } ] }, "result": { "type": [ "string", "null" ], "description": "What the action returned once it ran. Truncated." }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ], "description": "What the person said when they asked for the review: their point of view on the decision. Null if they gave none or no review was asked." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] }, "ApprovalList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Approval" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "Actor": { "type": "object", "properties": { "id": { "type": "string", "example": "user_8841", "description": "The id of the person in your system. Lelemon does not verify it: it is stored as declared by your key.", "pattern": "^[^\\r\\n]*$", "maxLength": 128, "minLength": 1 }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ], "description": "The role of the person in your system, from lowest to highest. A key of a subaccount cannot declare a role above staff." }, "name": { "type": "string", "example": "Ana Pérez", "pattern": "^[^\\r\\n]*$", "maxLength": 200, "minLength": 1 } }, "required": [ "id", "role" ] }, "DecideApproval": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000, "example": "Within the refund policy: order delivered damaged.", "description": "Why you decide this. Required for approving and for rejecting. It is stored with the decision and read by the auditor.", "minLength": 1, "pattern": "^[^\\u0000]*$" }, "actor": { "description": "The person in your system who decided. Lelemon records it as declared by this key, not verified. A key cannot declare a role above its own.", "type": "object", "properties": { "id": { "type": "string", "example": "user_8841", "description": "The id of the person in your system. Lelemon does not verify it: it is stored as declared by your key.", "pattern": "^[^\\r\\n]*$", "maxLength": 128, "minLength": 1 }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ], "description": "The role of the person in your system, from lowest to highest. A key of a subaccount cannot declare a role above staff." }, "name": { "type": "string", "example": "Ana Pérez", "pattern": "^[^\\r\\n]*$", "maxLength": 200, "minLength": 1 } }, "required": [ "id", "role" ] } }, "required": [ "reason" ] }, "RequestApprovalReview": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 1000, "description": "The point of view of the person on the decision, in their words. It is stored with the record, shown in reviewReason and sent in the review_requested event. Do not put anything the person did not say." } } }, "AutomatedDecision": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "automated_decision" ] }, "id": { "type": "string", "example": "dec_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ], "example": "cse_5RvP2aKq9XwLmN3tYbZc01" }, "tool": { "type": "string", "example": "approve_credit", "description": "The name of the action the agent decided about." }, "outcome": { "type": "string", "enum": [ "allowed", "rejected" ], "description": "allowed: the agent ran the action and no person was asked. rejected: a rule of the policy refused it and the action never ran." }, "reasonCode": { "type": "string", "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", "policy_not_required" ], "description": "Why: policy_rule (a rule of the policy decided: see ruleIndex) or policy_not_required (the policy did not ask for a person for this call)." }, "ruleIndex": { "type": [ "integer", "null" ], "description": "The position (from 0) of the rule that decided this, when reasonCode is policy_rule." }, "dataSeen": { "description": "The names of the argument fields the decision used. Never their values. Empty for a noPersist action.", "type": "array", "items": { "type": "string" } }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ], "description": "The point of view the person gave when they asked for the review." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "caseId", "tool", "outcome", "reasonCode", "ruleIndex", "dataSeen", "reviewRequestedAt", "reviewReason", "createdAt" ] }, "AutomatedDecisionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AutomatedDecision" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "TeamQuestion": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team_question" ] }, "id": { "type": "string", "example": "tqn_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "open", "answered", "delivered", "discarded" ], "description": "open waits for an answer. answered has the answer and the agent has not told the person yet. delivered: the agent told the person. discarded: it was closed without telling the person, for example because a human took the case." }, "caseId": { "type": "string", "example": "cse_5RvP2aKq9XwLmN3tYbZc01" }, "question": { "type": "string", "description": "What the agent needs to know, written for a person who did not see the conversation." }, "context": { "type": [ "string", "null" ], "description": "What the agent is trying to do and why it asks." }, "answer": { "type": [ "string", "null" ] }, "answerTitle": { "type": [ "string", "null" ] }, "answeredBy": { "type": [ "object", "null" ], "description": "Who answered: a member (mbr_ is not exposed here) or an API key (key_)." }, "answeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "caseId", "question", "context", "answer", "answerTitle", "answeredBy", "answeredAt", "deliveredAt", "createdAt", "updatedAt" ] }, "TeamQuestionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamQuestion" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "TeamQuestionMessage": { "type": "object", "properties": { "from": { "type": "string", "enum": [ "customer", "agent", "team" ], "description": "Who wrote it: the customer, the agent, or someone on your team." }, "text": { "type": "string", "description": "The text, shortened. A message that is not text (a voice note, an image) shows its type in brackets." }, "at": { "type": "string", "format": "date-time" } }, "required": [ "from", "text", "at" ] }, "TeamQuestionCaseField": { "type": "object", "properties": { "label": { "type": "string", "example": "Plan" }, "value": { "type": "string", "example": "Hosting Pro" } }, "required": [ "label", "value" ] }, "TeamQuestionContext": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team_question_context" ] }, "id": { "type": "string", "example": "tqn_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "open", "answered", "delivered", "discarded" ] }, "caseId": { "type": "string", "example": "cse_5RvP2aKq9XwLmN3tYbZc01" }, "contactName": { "type": [ "string", "null" ] }, "pipelineName": { "type": [ "string", "null" ] }, "question": { "type": "string", "description": "The question, with every sensitive value covered." }, "context": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "messages": { "description": "The last lines of the conversation with the customer, oldest first. Internal notes are left out.", "type": "array", "items": { "$ref": "#/components/schemas/TeamQuestionMessage" } }, "data": { "description": "The data of the case that is not sensitive, with the name of each field.", "type": "array", "items": { "$ref": "#/components/schemas/TeamQuestionCaseField" } }, "hiddenFields": { "description": "Names of the fields that hold sensitive values. Their values never appear here.", "type": "array", "items": { "type": "string" } } }, "required": [ "object", "id", "status", "caseId", "contactName", "pipelineName", "question", "context", "answer", "createdAt", "messages", "data", "hiddenFields" ] }, "AnswerTeamQuestion": { "type": "object", "properties": { "answer": { "type": "string", "maxLength": 4000, "example": "The order ships on Monday. Tell them the tracking number goes by email.", "description": "The answer, written as a colleague would say it. The agent does not forward it: it tells the person in its own words, in the context of the conversation.", "minLength": 1 }, "title": { "type": "string", "maxLength": 255, "description": "A title for the answer. Optional. Saving the answer as knowledge is a separate step: this does not create a knowledge document." } }, "required": [ "answer" ] }, "RunLimitsInput": { "type": "object", "properties": { "maxRounds": { "type": "integer", "minimum": 1, "default": 30, "description": "How many rounds the agent may take. Above 60 it is cut to 60." }, "maxMinutes": { "type": "integer", "minimum": 1, "default": 30, "description": "How many minutes it may last once it starts. Above 120 it is cut to 120." } } }, "CreateRun": { "type": "object", "properties": { "goal": { "type": "string", "maxLength": 8000, "example": "Reconcile the August bank statement of company 76.123.456-7 and tell me what is left pending.", "description": "What the agent has to achieve. It is treated as text from a user.", "minLength": 1 }, "actor": { "description": "The person in your system the agent works for. It travels signed by Lelemon to every action and MCP server of the run as the actor, marked as declared by your key and not verified. Without it the run works as your key. A key cannot declare a role above its own.", "type": "object", "properties": { "id": { "type": "string", "example": "user_8841", "description": "The id of the person in your system. Lelemon does not verify it: it is stored as declared by your key.", "pattern": "^[^\\r\\n]*$", "maxLength": 128, "minLength": 1 }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ], "description": "The role of the person in your system, from lowest to highest. A key of a subaccount cannot declare a role above staff." }, "name": { "type": "string", "example": "Ana Pérez", "pattern": "^[^\\r\\n]*$", "maxLength": 200, "minLength": 1 } }, "required": [ "id", "role" ] }, "limits": { "description": "Caps for this run. The server cuts them to its own maximums; what you leave out takes the default.", "type": "object", "properties": { "maxRounds": { "type": "integer", "minimum": 1, "default": 30, "description": "How many rounds the agent may take. Above 60 it is cut to 60." }, "maxMinutes": { "type": "integer", "minimum": 1, "default": 30, "description": "How many minutes it may last once it starts. Above 120 it is cut to 120." } } } }, "required": [ "goal" ] }, "RunLimits": { "type": "object", "properties": { "maxRounds": { "type": "integer", "description": "How many rounds the agent may take." }, "maxMinutes": { "type": "integer", "description": "How many minutes it may last once it starts." } }, "required": [ "maxRounds", "maxMinutes" ] }, "RunResult": { "type": "object", "properties": { "summary": { "type": "string", "description": "What the agent declared when it finished. It is a declaration: nobody has checked it yet." }, "checks": { "description": "What to look at to confirm the job is done, according to the agent.", "type": "array", "items": { "type": "string" } }, "partial": { "type": "string", "description": "The last thing the agent wrote. It comes also when the run stopped or failed. With stopReason no_conclusion it is the answer the agent gave in plain text instead of finishing." }, "error": { "type": "string", "description": "Why it failed. Only with status failed." }, "errorCode": { "type": "string", "description": "The API error code behind the failure, the same one the request would have returned (for example budget_exceeded when the run found the budget used up). Only with status failed, and only when the failure has one.", "example": "budget_exceeded" } } }, "RunActor": { "type": "object", "properties": { "id": { "type": "string", "example": "user_8841" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "name": { "type": "string", "example": "Ana Pérez", "description": "The name your key declared for this person, when it declared one." }, "declaredBy": { "type": "string", "example": "key_5RvP2aKq9XwLmN3tYbZc01", "description": "The API key that declared this person. Lelemon does not verify the person: the key vouches for them." } }, "required": [ "id", "role", "declaredBy" ] }, "Run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ], "description": "running: working, or in the queue. waiting_for_answer: paused to ask; question has it, answer it with POST /v2/runs/{id}/answer. completed_unverified: the agent says it finished and nobody has checked it, so do not read it as done. completed: a verifier checked it (it does not happen yet). stopped: the run was cut before the agent declared the job done, by a limit (rounds, time or the spending limit Lelemon sets for every run) or because the agent never concluded (no_conclusion) or repeated itself (loop); stopReason says which and result.partial keeps the last thing the agent wrote. failed: an error; result.error says what, or stopReason abandoned if nobody answered the pause in 30 days. canceled: you canceled it." }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "Why the run ended without finishing. Set with status stopped, and with status failed for abandoned. rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ], "description": "With status waiting_for_answer, what the agent asked. Answer it with POST /v2/runs/{id}/answer." }, "rounds": { "type": "integer", "description": "Rounds taken so far." }, "limits": { "$ref": "#/components/schemas/RunLimits" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/RunResult" }, { "type": "null" } ] }, "cancelRequested": { "type": "boolean", "description": "true if a cancel was asked. While a worker runs it, the run stops at the start of its next round." }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01", "description": "The scheduled task that started this run. null for a run you created with POST /v2/agents/{id}/runs." }, "actor": { "description": "The person the run works for, as declared by the key that created it. null when the run works as the key itself.", "anyOf": [ { "$ref": "#/components/schemas/RunActor" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] }, "RunList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AnswerRun": { "type": "object", "properties": { "answer": { "type": "string", "maxLength": 4000, "description": "The answer to what the agent asked.", "minLength": 1 }, "actor": { "description": "The person in your system who answered. Lelemon records it as declared by this key, not verified, and the agent sees who answered. Without it the answer comes from your key.", "type": "object", "properties": { "id": { "type": "string", "example": "user_8841", "description": "The id of the person in your system. Lelemon does not verify it: it is stored as declared by your key.", "pattern": "^[^\\r\\n]*$", "maxLength": 128, "minLength": 1 }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ], "description": "The role of the person in your system, from lowest to highest. A key of a subaccount cannot declare a role above staff." }, "name": { "type": "string", "example": "Ana Pérez", "pattern": "^[^\\r\\n]*$", "maxLength": 200, "minLength": 1 } }, "required": [ "id", "role" ] } }, "required": [ "answer" ] }, "ScheduledTaskContact": { "type": "object", "properties": { "contactId": { "type": "string", "example": "ctc_5RvP2aKq9XwLmN3tYbZc01", "description": "The contact the agent writes to. Send this or externalRef, exactly one. The contact needs an email address.", "maxLength": 40 }, "externalRef": { "type": "string", "example": "cliente-8841", "description": "The externalRef you gave the contact. Send this or contactId, exactly one. An email address is not accepted here.", "maxLength": 200 } } }, "ScheduledTaskOnReply": { "type": "object", "properties": { "instructions": { "type": "string", "example": "If the contact answers, help them read the report.", "maxLength": 4000, "description": "What the agent knows if the contact answers the email. The same agent keeps the conversation by email.", "minLength": 1 } }, "required": [ "instructions" ] }, "CreateScheduledTask": { "type": "object", "properties": { "name": { "type": "string", "example": "Monthly sales report", "maxLength": 200, "minLength": 1 }, "cron": { "type": "string", "example": "0 9 2 * *", "description": "Five fields: minute hour day-of-month month day-of-week. It is read in the timezone below. 422 invalid_cron if it cannot be read.", "maxLength": 120, "minLength": 1 }, "timezone": { "type": "string", "example": "America/Santiago", "default": "America/Santiago", "description": "An IANA timezone. 422 invalid_timezone if it is not one.", "maxLength": 64 }, "goal": { "type": "string", "example": "Send the sales report of the month to the contact.", "maxLength": 8000, "description": "The job the agent gets on each date, as in a run. The agent runs it unattended: it never stops to ask.", "minLength": 1 }, "contact": { "$ref": "#/components/schemas/ScheduledTaskContact" }, "channel": { "type": "string", "enum": [ "email" ], "description": "How the agent reaches the contact. Only email today. The agent needs the email channel." }, "from": { "type": "string", "example": "reports@acme.com", "description": "The sender. Its domain must be verified (POST /v2/email/domains). Without it the first verified domain is used.", "maxLength": 320 }, "onReply": { "$ref": "#/components/schemas/ScheduledTaskOnReply" }, "limits": { "$ref": "#/components/schemas/RunLimitsInput" }, "enabled": { "type": "boolean", "default": true } }, "required": [ "name", "cron", "goal", "contact", "channel" ] }, "ScheduledTask": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "schedule" ] }, "id": { "type": "string", "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "contactId": { "type": "string", "example": "ctc_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string", "example": "Monthly sales report" }, "cron": { "type": "string", "example": "0 9 2 * *" }, "timezone": { "type": "string", "example": "America/Santiago" }, "goal": { "type": "string", "description": "What the agent is asked to do on each date." }, "channel": { "type": "string", "enum": [ "email" ] }, "from": { "type": [ "string", "null" ], "example": "reports@acme.com" }, "onReply": { "anyOf": [ { "$ref": "#/components/schemas/ScheduledTaskOnReply" }, { "type": "null" } ] }, "limits": { "description": "The limits each run gets, after the server maximums.", "type": "object", "properties": { "maxRounds": { "type": "integer", "description": "How many rounds the agent may take." }, "maxMinutes": { "type": "integer", "description": "How many minutes it may last once it starts." } }, "required": [ "maxRounds", "maxMinutes" ] }, "enabled": { "type": "boolean" }, "pausedReason": { "type": [ "string", "null" ], "enum": [ "consecutive_failures", null ], "description": "Why the platform paused the task. consecutive_failures: three runs in a row failed or were cut." }, "nextRunAt": { "type": "string", "format": "date-time", "description": "When it fires next. A date missed while it was off is not replayed." }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "contactId", "name", "cron", "timezone", "goal", "channel", "from", "onReply", "limits", "enabled", "pausedReason", "nextRunAt", "lastRunAt", "createdAt", "updatedAt" ] }, "ScheduledTaskList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledTask" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateScheduledTask": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "minLength": 1 }, "cron": { "type": "string", "example": "30 8 * * 1", "maxLength": 120, "minLength": 1 }, "timezone": { "type": "string", "example": "America/Santiago", "maxLength": 64 }, "goal": { "type": "string", "maxLength": 8000, "minLength": 1 }, "contact": { "$ref": "#/components/schemas/ScheduledTaskContact" }, "limits": { "$ref": "#/components/schemas/RunLimitsInput" }, "enabled": { "type": "boolean", "description": "false pauses the task. true turns it on again from now, clears a platform pause and does not replay missed dates." } } }, "ScheduledTaskFire": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "schedule_fire" ] }, "status": { "type": "string", "enum": [ "fired", "skipped" ] }, "skipReason": { "type": [ "string", "null" ], "description": "Why no run started. Set with status skipped." }, "run": { "anyOf": [ { "$ref": "#/components/schemas/Run" }, { "type": "null" } ] } }, "required": [ "object", "status", "skipReason", "run" ] }, "InitialStage": { "type": "object", "properties": { "name": { "type": "string", "example": "New", "maxLength": 255, "minLength": 1 }, "entry": { "type": "boolean", "description": "Marks the stage where new cases start. The first stage is the entry when none says so." }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that works cases in this stage." } }, "required": [ "name" ] }, "QuickReply": { "type": "object", "properties": { "shortcut": { "type": "string", "example": "hours", "description": "1 to 30 lowercase letters, numbers, hyphens or underscores. Unique in the pipeline." }, "text": { "type": "string", "example": "We are open from 12:00 to 24:00.", "description": "Up to 4096 characters.", "maxLength": 4096, "minLength": 1 } }, "required": [ "shortcut", "text" ] }, "AutoClose": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Turns the automatic close on or off." }, "inactivityMinutes": { "type": "integer", "example": 120, "description": "Minutes of silence before the case closes, from 5 to 525600. Counted inside the business hours when the pipeline has them.", "maximum": 525600, "minimum": 5 }, "message": { "type": [ "string", "null" ], "description": "Farewell sent when the case closes, up to 1000 characters. It needs inactivityMinutes under 1440, because after 24 hours the WhatsApp window is closed.", "maxLength": 1000 }, "closeStageId": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage where the case is left when it closes. A stage of this pipeline." }, "includeTaken": { "type": "boolean", "description": "Also close the chats a person has taken over." }, "reopenWindowHours": { "type": "integer", "description": "Hours after the close when a new message reopens the case, from 0 to 720. 24 when omitted.", "maximum": 720, "minimum": 0 } }, "required": [ "enabled", "inactivityMinutes" ] }, "TimeRange": { "type": "object", "properties": { "from": { "type": "string", "example": "09:00", "description": "HH:MM, 00:00 to 23:59.", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "to": { "type": "string", "example": "18:00", "description": "HH:MM, after from. 24:00 is the end of the day.", "pattern": "^(([01]\\d|2[0-3]):[0-5]\\d|24:00)$" } }, "required": [ "from", "to" ] }, "PipelineBusinessDays": { "type": "object", "properties": { "mon": { "description": "Ranges on Monday. An empty list closes the day.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "tue": { "description": "Ranges on Tuesday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "wed": { "description": "Ranges on Wednesday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "thu": { "description": "Ranges on Thursday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "fri": { "description": "Ranges on Friday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "sat": { "description": "Ranges on Saturday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "sun": { "description": "Ranges on Sunday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 } } }, "Holiday": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-12-25", "description": "YYYY-MM-DD.", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "ranges": { "description": "Ranges that replace the ones of that weekday. Without ranges the day is closed.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 } }, "required": [ "date" ] }, "PipelineBusinessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Santiago", "description": "IANA time zone. Santiago when omitted.", "maxLength": 64 }, "days": { "description": "Ranges per weekday. A day that is not here is closed. Without days the pipeline attends 24/7.", "type": "object", "properties": { "mon": { "description": "Ranges on Monday. An empty list closes the day.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "tue": { "description": "Ranges on Tuesday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "wed": { "description": "Ranges on Wednesday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "thu": { "description": "Ranges on Thursday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "fri": { "description": "Ranges on Friday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "sat": { "description": "Ranges on Saturday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 }, "sun": { "description": "Ranges on Sunday.", "type": "array", "items": { "$ref": "#/components/schemas/TimeRange" }, "maxItems": 10 } } }, "holidays": { "type": "array", "items": { "$ref": "#/components/schemas/Holiday" }, "maxItems": 400 } } }, "WaitThresholds": { "type": "object", "properties": { "yellowMinutes": { "type": "number", "example": 10, "description": "Minutes without an answer before the wait turns yellow.", "minimum": 1 }, "redMinutes": { "type": "number", "example": 30, "description": "Minutes without an answer before the wait turns red. Greater than yellowMinutes.", "minimum": 1 } } }, "PipelineSettings": { "type": "object", "properties": { "timezone": { "type": [ "string", "null" ], "example": "America/Santiago", "description": "IANA time zone for the scheduled work of the pipeline.", "maxLength": 64 }, "askFor": { "type": [ "string", "null" ], "enum": [ "one_at_a_time", "in_order", null ], "description": "How the agent asks for the fields it fills: one_at_a_time as the conversation goes, or in_order following the order of the fields. null goes back to one_at_a_time." }, "autoClose": { "description": "Closes the cases that go silent. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/AutoClose" }, { "type": "null" } ] }, "businessHours": { "description": "When the pipeline attends. The wait colors, the auto close and the warning before it count only inside these hours. Replaces the whole block; null goes back to counting the clock all day.", "anyOf": [ { "$ref": "#/components/schemas/PipelineBusinessHours" }, { "type": "null" } ] }, "waitThresholds": { "description": "When the wait of a case turns yellow and red. Replaces the whole block; null goes back to 10 and 30 minutes.", "anyOf": [ { "$ref": "#/components/schemas/WaitThresholds" }, { "type": "null" } ] }, "stageOnTakeControl": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage a case moves to when a person takes control. A stage of this pipeline; it cannot be set on creation. null leaves cases where they are." }, "stageOnHandoff": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage a case moves to when the agent hands it to a person. A stage of this pipeline; it cannot be set on creation. null leaves cases where they are." } } }, "CreatePipeline": { "type": "object", "properties": { "name": { "type": "string", "example": "Orders", "maxLength": 255, "minLength": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "stages": { "description": "Create stages in the same call, in order.", "type": "array", "items": { "$ref": "#/components/schemas/InitialStage" }, "maxItems": 50 }, "quickReplies": { "type": "array", "items": { "$ref": "#/components/schemas/QuickReply" }, "maxItems": 50 }, "settings": { "description": "Settings of the pipeline. A stage cannot be named here because the pipeline has none yet: set stageOnTakeControl, stageOnHandoff and autoClose.closeStageId with PATCH.", "type": "object", "properties": { "timezone": { "type": [ "string", "null" ], "example": "America/Santiago", "description": "IANA time zone for the scheduled work of the pipeline.", "maxLength": 64 }, "askFor": { "type": [ "string", "null" ], "enum": [ "one_at_a_time", "in_order", null ], "description": "How the agent asks for the fields it fills: one_at_a_time as the conversation goes, or in_order following the order of the fields. null goes back to one_at_a_time." }, "autoClose": { "description": "Closes the cases that go silent. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/AutoClose" }, { "type": "null" } ] }, "businessHours": { "description": "When the pipeline attends. The wait colors, the auto close and the warning before it count only inside these hours. Replaces the whole block; null goes back to counting the clock all day.", "anyOf": [ { "$ref": "#/components/schemas/PipelineBusinessHours" }, { "type": "null" } ] }, "waitThresholds": { "description": "When the wait of a case turns yellow and red. Replaces the whole block; null goes back to 10 and 30 minutes.", "anyOf": [ { "$ref": "#/components/schemas/WaitThresholds" }, { "type": "null" } ] }, "stageOnTakeControl": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage a case moves to when a person takes control. A stage of this pipeline; it cannot be set on creation. null leaves cases where they are." }, "stageOnHandoff": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage a case moves to when the agent hands it to a person. A stage of this pipeline; it cannot be set on creation. null leaves cases where they are." } } } }, "required": [ "name" ] }, "PipelineSettingsResponse": { "type": "object", "properties": { "timezone": { "type": [ "string", "null" ] }, "askFor": { "type": "string", "enum": [ "one_at_a_time", "in_order" ] }, "autoClose": { "anyOf": [ { "$ref": "#/components/schemas/AutoClose" }, { "type": "null" } ] }, "businessHours": { "anyOf": [ { "$ref": "#/components/schemas/PipelineBusinessHours" }, { "type": "null" } ] }, "waitThresholds": { "anyOf": [ { "$ref": "#/components/schemas/WaitThresholds" }, { "type": "null" } ] }, "stageOnTakeControl": { "type": [ "string", "null" ] }, "stageOnHandoff": { "type": [ "string", "null" ] } }, "required": [ "timezone", "askFor", "autoClose", "businessHours", "waitThresholds", "stageOnTakeControl", "stageOnHandoff" ] }, "Pipeline": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "pipeline" ] }, "id": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "name": { "type": "string", "example": "Orders" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "stages": { "example": [ "stg_N3wX2mRw0TqS9mYp3LkQ8d" ], "description": "The ids of its stages, in order.", "type": "array", "items": { "type": "string" } }, "quickReplies": { "type": "array", "items": { "$ref": "#/components/schemas/QuickReply" } }, "settings": { "$ref": "#/components/schemas/PipelineSettingsResponse" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "description", "status", "stages", "quickReplies", "settings", "createdAt", "updatedAt" ] }, "PipelineList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "ClonePipeline": { "type": "object", "properties": { "name": { "type": "string", "example": "Orders" } }, "required": [ "name" ] }, "ReorderStages": { "type": "object", "properties": { "stages": { "example": [ "stg_5RvP2aKq9XwLmN3tYbZc01", "stg_7HnQ4cLs2YdTpK8wVfXa03" ], "description": "Every stage of the pipeline, once each, in the order they should have: the first one takes position 0. A stage that is missing, repeated or from another pipeline is a 400 with param stages and nothing changes.", "type": "array", "items": { "type": "string" }, "maxItems": 200 } }, "required": [ "stages" ] }, "UpdatePipeline": { "type": "object", "properties": { "name": { "type": "string", "example": "Orders", "maxLength": 255, "minLength": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "quickReplies": { "description": "Replaces the whole list. An empty list removes them all.", "type": "array", "items": { "$ref": "#/components/schemas/QuickReply" }, "maxItems": 50 }, "settings": { "description": "Only the settings you send change. Each block (autoClose, businessHours, waitThresholds) replaces the whole block, and null removes a setting.", "type": "object", "properties": { "timezone": { "type": [ "string", "null" ], "example": "America/Santiago", "description": "IANA time zone for the scheduled work of the pipeline.", "maxLength": 64 }, "askFor": { "type": [ "string", "null" ], "enum": [ "one_at_a_time", "in_order", null ], "description": "How the agent asks for the fields it fills: one_at_a_time as the conversation goes, or in_order following the order of the fields. null goes back to one_at_a_time." }, "autoClose": { "description": "Closes the cases that go silent. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/AutoClose" }, { "type": "null" } ] }, "businessHours": { "description": "When the pipeline attends. The wait colors, the auto close and the warning before it count only inside these hours. Replaces the whole block; null goes back to counting the clock all day.", "anyOf": [ { "$ref": "#/components/schemas/PipelineBusinessHours" }, { "type": "null" } ] }, "waitThresholds": { "description": "When the wait of a case turns yellow and red. Replaces the whole block; null goes back to 10 and 30 minutes.", "anyOf": [ { "$ref": "#/components/schemas/WaitThresholds" }, { "type": "null" } ] }, "stageOnTakeControl": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage a case moves to when a person takes control. A stage of this pipeline; it cannot be set on creation. null leaves cases where they are." }, "stageOnHandoff": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage a case moves to when the agent hands it to a person. A stage of this pipeline; it cannot be set on creation. null leaves cases where they are." } } } } }, "Condition": { "type": "object", "properties": { "field": { "type": "string", "example": "data.amount", "description": "Path of the value.", "maxLength": 255 }, "operator": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "contains", "exists", "in" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } ], "example": 1000, "description": "What to compare with: a text, a number, a boolean, or a list for in. exists does not need one." } }, "required": [ "field", "operator" ] }, "Transition": { "type": "object", "properties": { "targetStageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "A stage of the same pipeline." }, "priority": { "type": "integer", "minimum": 0, "description": "Lower numbers are tried first.", "maximum": 1000 }, "conditions": { "description": "All of them must hold. Empty always holds.", "type": "array", "items": { "$ref": "#/components/schemas/Condition" }, "maxItems": 50 } }, "required": [ "targetStageId", "priority", "conditions" ] }, "FollowUp": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Turns the follow-ups of this stage on or off." }, "delays": { "example": [ 240, 1440, 2880 ], "description": "Minutes of silence before each follow-up. A negative number counts before an event, as in a meeting reminder.", "type": "array", "items": { "type": "integer" }, "maxItems": 20 }, "maxAttempts": { "type": "integer", "minimum": 1, "description": "Follow-ups to send before the last one.", "maximum": 20 }, "templateSequence": { "type": "array", "description": "What each follow-up says, in order.", "items": { "type": "string", "enum": [ "reengagement", "reminder", "last_chance", "breakup", "demo_reminder", "no_show" ] }, "maxItems": 20 }, "allowTemplates": { "type": "boolean", "description": "Send WhatsApp templates once the 24-hour window is closed. They cost money. false when omitted." }, "maxTemplates": { "type": "integer", "minimum": 1, "maximum": 5, "description": "Most templates to send. 1 when omitted." } }, "required": [ "enabled", "delays", "maxAttempts", "templateSequence" ] }, "NoProgress": { "type": "object", "properties": { "minutes": { "type": "integer", "minimum": 1, "maximum": 525600, "example": 1440, "description": "Minutes a case can stay in the stage before the team gets a task. They count only inside the business hours of the pipeline, when it has them." }, "title": { "type": "string", "maxLength": 255, "example": "Llamar al contador", "description": "Title of the task. It is a reminder of type call.", "pattern": "\\S" }, "description": { "type": "string", "maxLength": 2000, "description": "Description of the task." }, "fallbackAssigneeId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Member who gets the task when the case has no assignee. An active member of the organization. Without it, a case with no assignee gets no task." }, "tag": { "type": "string", "maxLength": 50, "example": "llamar", "description": "Tag added to the contact of the case when the task is created.", "pattern": "\\S" } }, "required": [ "minutes", "title" ] }, "StageConfig": { "type": "object", "properties": { "agentMode": { "type": [ "string", "null" ], "enum": [ "always", "paused", "outside_business_hours", null ], "description": "When the agent of the stage answers: always, never (paused) or only outside the business hours of the organization. null goes back to always." }, "attentionRole": { "type": [ "string", "null" ], "enum": [ "escalation", "answer", null ], "description": "The part the stage plays in the attention queue. escalation: cases here wait for the technical team and show as waiting for a reply to whoever escalated them. answer: cases here came back with an answer and the customer still needs a reply; the owner is notified when a case enters. null removes the role." }, "followUp": { "description": "Messages the stage sends to a person who went silent. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/FollowUp" }, { "type": "null" } ] }, "maxDurationSeconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Longest duration, in seconds.", "maximum": 86400 }, "minDurationSeconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Shortest duration, in seconds, for a valid completion.", "maximum": 86400 }, "delayMinutes": { "type": [ "integer", "null" ], "minimum": 1, "description": "Minutes a case waits in the stage before it moves on.", "maximum": 525600 }, "noProgress": { "description": "Creates a task for the team when a case stays in the stage too long. One task per pass of the case through the stage; it closes by itself when the case moves on or closes. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/NoProgress" }, { "type": "null" } ] } } }, "CreateStage": { "type": "object", "properties": { "closes": { "type": "boolean", "description": "true makes arriving at this stage end the conversation: the next message from the person starts a new case. A stage with statusType done ends it too." }, "closingOutcome": { "type": [ "string", "null" ], "example": "Resolved", "description": "Why the case closed, written in the case when it arrives here, up to 50 characters. It only counts in a stage that closes. null removes it.", "maxLength": 50 }, "statusType": { "type": [ "string", "null" ], "enum": [ "todo", "in_progress", "done", null ], "description": "What the stage means in the pipeline: todo, in_progress or done. null leaves it without a type." }, "nextStageId": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage that follows when no transition holds. A stage of the same pipeline; null removes it." }, "transitions": { "description": "Where a case goes from this stage, with their conditions. Replaces the whole list; an empty list removes them all.", "type": "array", "items": { "$ref": "#/components/schemas/Transition" }, "maxItems": 50 }, "config": { "description": "Settings of the stage. Only the keys you send change, and null removes one.", "type": "object", "properties": { "agentMode": { "type": [ "string", "null" ], "enum": [ "always", "paused", "outside_business_hours", null ], "description": "When the agent of the stage answers: always, never (paused) or only outside the business hours of the organization. null goes back to always." }, "attentionRole": { "type": [ "string", "null" ], "enum": [ "escalation", "answer", null ], "description": "The part the stage plays in the attention queue. escalation: cases here wait for the technical team and show as waiting for a reply to whoever escalated them. answer: cases here came back with an answer and the customer still needs a reply; the owner is notified when a case enters. null removes the role." }, "followUp": { "description": "Messages the stage sends to a person who went silent. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/FollowUp" }, { "type": "null" } ] }, "maxDurationSeconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Longest duration, in seconds.", "maximum": 86400 }, "minDurationSeconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Shortest duration, in seconds, for a valid completion.", "maximum": 86400 }, "delayMinutes": { "type": [ "integer", "null" ], "minimum": 1, "description": "Minutes a case waits in the stage before it moves on.", "maximum": 525600 }, "noProgress": { "description": "Creates a task for the team when a case stays in the stage too long. One task per pass of the case through the stage; it closes by itself when the case moves on or closes. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/NoProgress" }, { "type": "null" } ] } } }, "name": { "type": "string", "example": "Ordering", "maxLength": 255, "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "description": "Where it goes among the stages, from 0. At the end when omitted.", "maximum": 1000 }, "entry": { "type": "boolean", "description": "Makes it the stage where new cases start. The first stage of a pipeline is the entry when none says so." }, "agentId": { "type": [ "string", "null" ], "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that works cases in this stage." }, "requiredFields": { "example": [ "address" ], "description": "Keys of fields a case needs before it can enter this stage.", "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "required": [ "name" ] }, "StageConfigResponse": { "type": "object", "properties": { "agentMode": { "type": [ "string", "null" ], "enum": [ "always", "paused", "outside_business_hours", null ] }, "attentionRole": { "type": [ "string", "null" ], "enum": [ "escalation", "answer", null ] }, "followUp": { "anyOf": [ { "$ref": "#/components/schemas/FollowUp" }, { "type": "null" } ] }, "maxDurationSeconds": { "type": [ "integer", "null" ] }, "minDurationSeconds": { "type": [ "integer", "null" ] }, "delayMinutes": { "type": [ "integer", "null" ] }, "noProgress": { "anyOf": [ { "$ref": "#/components/schemas/NoProgress" }, { "type": "null" } ] } }, "required": [ "agentMode", "attentionRole", "followUp", "maxDurationSeconds", "minDurationSeconds", "delayMinutes", "noProgress" ] }, "Stage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "stage" ] }, "id": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ" }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "name": { "type": "string", "example": "Ordering" }, "position": { "type": "integer", "example": 0 }, "entry": { "type": "boolean" }, "agentId": { "type": [ "string", "null" ] }, "requiredFields": { "example": [ "address" ], "type": "array", "items": { "type": "string" } }, "closes": { "type": "boolean" }, "closingOutcome": { "type": [ "string", "null" ] }, "statusType": { "type": [ "string", "null" ], "enum": [ "todo", "in_progress", "done", null ] }, "nextStageId": { "type": [ "string", "null" ] }, "transitions": { "type": "array", "items": { "$ref": "#/components/schemas/Transition" } }, "config": { "$ref": "#/components/schemas/StageConfigResponse" }, "whatsappPhoneNumberId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "pipelineId", "name", "position", "entry", "agentId", "requiredFields", "closes", "closingOutcome", "statusType", "nextStageId", "transitions", "config", "whatsappPhoneNumberId", "createdAt", "updatedAt" ] }, "StageList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateStage": { "type": "object", "properties": { "closes": { "type": "boolean", "description": "true makes arriving at this stage end the conversation: the next message from the person starts a new case. A stage with statusType done ends it too." }, "closingOutcome": { "type": [ "string", "null" ], "example": "Resolved", "description": "Why the case closed, written in the case when it arrives here, up to 50 characters. It only counts in a stage that closes. null removes it.", "maxLength": 50 }, "statusType": { "type": [ "string", "null" ], "enum": [ "todo", "in_progress", "done", null ], "description": "What the stage means in the pipeline: todo, in_progress or done. null leaves it without a type." }, "nextStageId": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage that follows when no transition holds. A stage of the same pipeline; null removes it." }, "transitions": { "description": "Where a case goes from this stage, with their conditions. Replaces the whole list; an empty list removes them all.", "type": "array", "items": { "$ref": "#/components/schemas/Transition" }, "maxItems": 50 }, "config": { "description": "Settings of the stage. Only the keys you send change, and null removes one.", "type": "object", "properties": { "agentMode": { "type": [ "string", "null" ], "enum": [ "always", "paused", "outside_business_hours", null ], "description": "When the agent of the stage answers: always, never (paused) or only outside the business hours of the organization. null goes back to always." }, "attentionRole": { "type": [ "string", "null" ], "enum": [ "escalation", "answer", null ], "description": "The part the stage plays in the attention queue. escalation: cases here wait for the technical team and show as waiting for a reply to whoever escalated them. answer: cases here came back with an answer and the customer still needs a reply; the owner is notified when a case enters. null removes the role." }, "followUp": { "description": "Messages the stage sends to a person who went silent. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/FollowUp" }, { "type": "null" } ] }, "maxDurationSeconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Longest duration, in seconds.", "maximum": 86400 }, "minDurationSeconds": { "type": [ "integer", "null" ], "minimum": 1, "description": "Shortest duration, in seconds, for a valid completion.", "maximum": 86400 }, "delayMinutes": { "type": [ "integer", "null" ], "minimum": 1, "description": "Minutes a case waits in the stage before it moves on.", "maximum": 525600 }, "noProgress": { "description": "Creates a task for the team when a case stays in the stage too long. One task per pass of the case through the stage; it closes by itself when the case moves on or closes. Replaces the whole block; null removes it.", "anyOf": [ { "$ref": "#/components/schemas/NoProgress" }, { "type": "null" } ] } } }, "name": { "type": "string", "example": "Ordering", "maxLength": 255, "minLength": 1 }, "position": { "type": "integer", "minimum": 0, "maximum": 1000 }, "entry": { "type": "boolean", "description": "true makes it the entry and unmarks the previous one. false is refused: make another stage the entry instead." }, "agentId": { "type": [ "string", "null" ], "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "null unlinks the agent." }, "requiredFields": { "description": "Replaces the list.", "type": "array", "items": { "type": "string" }, "maxItems": 100 }, "whatsappPhoneNumberId": { "type": [ "string", "null" ], "example": "pn_5Zq0x8bVw1TqS9mYp3RkLd", "description": "A WhatsApp number of the organization. Messages that arrive at it start their cases in this stage. A number can feed one pipeline only. null releases it." } } }, "FieldOption": { "type": "object", "properties": { "value": { "type": "string", "example": "margherita", "maxLength": 80, "minLength": 1 }, "label": { "type": "string", "example": "Margherita", "description": "What people see. Defaults to the value.", "maxLength": 80 }, "whenParent": { "description": "Only on a field with dependsOn: the values of the parent field that offer this option. Omitted means always.", "type": "array", "items": { "type": "string" }, "maxItems": 200 } }, "required": [ "value" ] }, "CreateField": { "type": "object", "properties": { "key": { "type": "string", "example": "address", "description": "Letters, numbers and underscores, starting with a letter. Unique in the pipeline and fixed once created.", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }, "type": { "type": "string", "enum": [ "text", "email", "phone", "url", "textarea", "file", "select" ] }, "label": { "type": "string", "example": "Address", "description": "Defaults to the key.", "maxLength": 255, "minLength": 1 }, "required": { "type": "boolean", "default": false }, "options": { "description": "Only for type select.", "type": "array", "items": { "$ref": "#/components/schemas/FieldOption" }, "maxItems": 2000 }, "dependsOn": { "type": [ "string", "null" ], "example": "category", "description": "The key of a select field this one depends on. One level only." }, "source": { "type": "string", "enum": [ "team", "channel", "system", "agent" ], "default": "team", "description": "Who fills it: the team, the channel, your system or the agent." }, "instruction": { "type": [ "string", "null" ], "description": "What the agent should ask or look for.", "maxLength": 1000 }, "sensitive": { "type": "boolean", "default": false, "description": "Hides its value from the agent and from webhooks." } }, "required": [ "key", "type" ] }, "Field": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "field" ] }, "id": { "type": "string", "example": "fld_7AdX2mRw0TqS9mYp3LkQ8d" }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "key": { "type": "string", "example": "address" }, "label": { "type": "string", "example": "Address" }, "type": { "type": "string", "enum": [ "text", "email", "phone", "url", "textarea", "file", "select" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/FieldOption" } }, "dependsOn": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "team", "channel", "system", "agent" ] }, "instruction": { "type": [ "string", "null" ] }, "sensitive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "pipelineId", "key", "label", "type", "required", "options", "dependsOn", "source", "instruction", "sensitive", "createdAt", "updatedAt" ] }, "FieldList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateField": { "type": "object", "properties": { "label": { "type": "string", "example": "Address", "maxLength": 255, "minLength": 1 }, "required": { "type": "boolean" }, "options": { "description": "Replaces the options. Cases keep the values they have.", "type": "array", "items": { "$ref": "#/components/schemas/FieldOption" }, "maxItems": 2000 }, "dependsOn": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "team", "channel", "system", "agent" ] }, "instruction": { "type": [ "string", "null" ], "maxLength": 1000 }, "sensitive": { "type": "boolean" } } }, "CreateRoutingRule": { "type": "object", "properties": { "fromStageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage of this pipeline that triggers the rule." }, "toPipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ", "description": "The pipeline the case goes to." }, "toStageId": { "type": [ "string", "null" ], "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "A stage of the destination. Its entry stage when omitted." }, "mode": { "type": "string", "enum": [ "create", "move" ], "default": "create", "description": "create opens a new case in the destination and keeps this one. move takes the case there." }, "enabled": { "type": "boolean", "default": true } }, "required": [ "fromStageId", "toPipelineId" ] }, "RoutingRule": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "routing_rule" ] }, "id": { "type": "string", "example": "rr_3ZqX2mRw0TqS9mYp3LkQ8d" }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "fromStageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ" }, "toPipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "toStageId": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "create", "move" ] }, "enabled": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "pipelineId", "fromStageId", "toPipelineId", "toStageId", "mode", "enabled", "createdAt", "updatedAt" ] }, "RoutingRuleList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingRule" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateRoutingRule": { "type": "object", "properties": { "toStageId": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "create", "move" ] }, "enabled": { "type": "boolean" } } }, "CreateKnowledgeCollection": { "type": "object", "properties": { "name": { "type": "string", "example": "FAQ", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "description": { "type": [ "string", "null" ], "example": "Questions customers ask every day.", "maxLength": 2000 } }, "required": [ "name" ] }, "KnowledgeCollection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_collection" ] }, "id": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string", "example": "FAQ" }, "description": { "type": [ "string", "null" ] }, "documentCount": { "type": "integer", "description": "Documents in any status." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "description", "documentCount", "createdAt", "updatedAt" ] }, "SearchKnowledge": { "type": "object", "properties": { "query": { "type": "string", "example": "What is the return policy?", "maxLength": 1000, "description": "What you are looking for, in your own words. It searches by meaning and by exact words (a product code, a name).", "minLength": 1 }, "collectionIds": { "example": [ "kbc_2LpX0x8bVw1TqS9mYp3RkL" ], "maxItems": 20, "description": "Search only these collections. Leave it out to search all of them.", "type": "array", "items": { "type": "string", "maxLength": 64 } }, "limit": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5, "description": "How many passages to return, best first." } }, "required": [ "query" ] }, "KnowledgePassage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_passage" ] }, "collectionId": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "collectionName": { "type": "string", "example": "FAQ" }, "documentId": { "type": "string", "example": "kbd_02y0e5MANqacVbmtn1YyeJ" }, "documentName": { "type": "string", "example": "returns.pdf" }, "sourceUrl": { "type": [ "string", "null" ], "description": "Where the document came from, when it has an address." }, "text": { "type": "string", "description": "The passage of the document." }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1, "description": "How close the passage is in meaning, from 0 to 1. It is null when the passage was found only by its exact words." } }, "required": [ "object", "collectionId", "collectionName", "documentId", "documentName", "sourceUrl", "text", "score" ] }, "KnowledgeSearch": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_search" ] }, "data": { "description": "Best first. An empty list means nothing in the knowledge answers it.", "type": "array", "items": { "$ref": "#/components/schemas/KnowledgePassage" } } }, "required": [ "object", "data" ] }, "KnowledgeCollectionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeCollection" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateKnowledgeCollection": { "type": "object", "properties": { "name": { "type": "string", "example": "FAQ", "minLength": 1, "maxLength": 255, "pattern": "\\S" }, "description": { "type": [ "string", "null" ], "description": "null clears it.", "maxLength": 2000 } } }, "CreateKnowledgeDocument": { "type": "object", "properties": { "name": { "type": "string", "example": "horarios.md", "maxLength": 500, "description": "Required with text. With a file it defaults to the file name. The same name in a collection replaces the document.", "pattern": "\\S" }, "text": { "type": "string", "example": "Abrimos de 12:00 a 24:00.", "description": "The content as text. Send either text or a file, not both.", "pattern": "\\S" }, "file": { "type": "string", "format": "binary", "description": "Multipart only. PDF, DOCX, TXT or MD, up to 15 MB. Send either a file or text." } } }, "KnowledgeDocumentError": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "text_extraction_failed", "no_text_found", "embedding_failed", "processing_failed", "enqueue_failed" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "KnowledgeDocument": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_document" ] }, "id": { "type": "string", "example": "kbd_02y0e5MANqacVbmtn1YyeJ" }, "collectionId": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string", "example": "faq.pdf" }, "mimeType": { "type": "string", "example": "application/pdf" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "chunkCount": { "type": "integer", "description": "Searchable passages." }, "error": { "description": "Set when status is failed.", "anyOf": [ { "$ref": "#/components/schemas/KnowledgeDocumentError" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "collectionId", "name", "mimeType", "sizeBytes", "status", "chunkCount", "error", "createdAt", "updatedAt" ] }, "KnowledgeDocumentList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/KnowledgeDocument" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "KnowledgeDocumentWithContent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_document" ] }, "id": { "type": "string", "example": "kbd_02y0e5MANqacVbmtn1YyeJ" }, "collectionId": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string", "example": "faq.pdf" }, "mimeType": { "type": "string", "example": "application/pdf" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "chunkCount": { "type": "integer", "description": "Searchable passages." }, "error": { "description": "Set when status is failed.", "anyOf": [ { "$ref": "#/components/schemas/KnowledgeDocumentError" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "content": { "type": [ "string", "null" ], "description": "The text the agent searches. null until status is ready." } }, "required": [ "object", "id", "collectionId", "name", "mimeType", "sizeBytes", "status", "chunkCount", "error", "createdAt", "updatedAt", "content" ] }, "UpdateKnowledgeDocument": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 500, "pattern": "\\S" }, "text": { "type": "string", "description": "Replaces the content and processes the document again: status goes back to processing.", "pattern": "\\S" } } }, "AgentKnowledgeCollection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agent_knowledge_collection" ] }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd" }, "collectionId": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "granted": { "type": "boolean", "example": true } }, "required": [ "object", "agentId", "collectionId", "granted" ] }, "CreateContact": { "type": "object", "properties": { "name": { "type": "string", "example": "Ana Pérez", "maxLength": 255, "minLength": 1 }, "email": { "type": "string", "example": "ana@example.com", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "example": "+56912345678", "maxLength": 50, "minLength": 1 }, "externalRef": { "type": "string", "example": "crm-4471", "description": "Your own id for this person. Unique in the organization: sending it again is a 409.", "maxLength": 255, "minLength": 1 }, "companyId": { "type": "string", "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The company this person works in, created with POST /v2/companies. A company that does not exist in the organization is a 400 with param companyId." }, "tags": { "example": [ "vip" ], "type": "array", "items": { "type": "string", "pattern": "^[^\\s,][^,]{0,48}$" }, "maxItems": 20 }, "fields": { "type": "object", "additionalProperties": true, "example": { "plan": "pro" }, "description": "Values for the contact fields you created with POST /v2/contact-fields, by key. Each value is checked against the type of its field. Nothing is saved if one key or value is not accepted." } }, "required": [ "name" ] }, "Presence": { "type": "object", "properties": { "online": { "type": "boolean", "description": "true when the last active signal is less than 120 seconds old and no offline signal came after." }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The last time a signal arrived. While online it is exact; once offline it can be up to 5 minutes behind. null when no signal ever arrived for this contact." } }, "required": [ "online", "lastSeenAt" ] }, "Contact": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "contact" ] }, "id": { "type": "string", "example": "ctc_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Ana Pérez" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "externalRef": { "type": [ "string", "null" ] }, "companyId": { "type": [ "string", "null" ], "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The company of this contact, or null when it has none." }, "tags": { "type": "array", "items": { "type": "string" } }, "fields": { "type": "object", "additionalProperties": true, "example": { "plan": "pro" }, "description": "The values of the contact fields this contact has, by key. Empty when it has none." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "presence": { "description": "Whether the contact is online. Present only when the organization setting presenceEnabled is on, at least one presence signal has arrived, and the key has the contacts:presence-read scope.", "type": "object", "properties": { "online": { "type": "boolean", "description": "true when the last active signal is less than 120 seconds old and no offline signal came after." }, "lastSeenAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The last time a signal arrived. While online it is exact; once offline it can be up to 5 minutes behind. null when no signal ever arrived for this contact." } }, "required": [ "online", "lastSeenAt" ] }, "match": { "type": [ "object", "null" ], "properties": { "field": { "type": "string", "example": "Plan" }, "value": { "type": "string", "example": "enterprise" } }, "description": "Only when you search with q: the field of the contact that matched and its value, or null when the match was the name, email, phone or externalRef. Fields marked sensitive are never searched or shown." }, "caseCount": { "type": "integer", "description": "Only when you search, filter by pipeline or open cases, or sort: how many cases the contact has." }, "openCaseCount": { "type": "integer", "description": "Same as caseCount, only the open ones." }, "lastActivityAt": { "type": "string", "format": "date-time", "description": "Same as caseCount: the latest message of its cases, or its creation date." } }, "required": [ "object", "id", "name", "email", "phone", "externalRef", "companyId", "tags", "fields", "createdAt", "updatedAt" ] }, "ContactList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpsertContact": { "type": "object", "properties": { "name": { "type": "string", "example": "Ana Pérez", "description": "Required to create. When the contact exists and you omit it, the name stays. A new contact with no name is named after the externalRef.", "maxLength": 255, "minLength": 1 }, "email": { "type": "string", "example": "ana@example.com", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "example": "+56912345678", "maxLength": 50, "minLength": 1 }, "companyId": { "type": [ "string", "null" ], "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Links the contact to a company. When you omit it the company stays; null unlinks it. A company that does not exist in the organization is a 400 with param companyId." }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[^\\s,][^,]{0,48}$" }, "maxItems": 20 }, "fields": { "type": "object", "additionalProperties": true, "example": { "plan": "pro", "segment": null }, "description": "Values for the contact fields you created with POST /v2/contact-fields, by key. The keys you omit stay as they were; null removes the value. Each value is checked against the type of its field. Nothing is saved if one key or value is not accepted." } } }, "UpdateContact": { "type": "object", "properties": { "name": { "type": "string", "example": "Ana Pérez", "maxLength": 255, "minLength": 1 }, "email": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "phone": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 50, "minLength": 1 }, "externalRef": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 255, "minLength": 1 }, "companyId": { "type": [ "string", "null" ], "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Links the contact to a company, or to another one. null unlinks it. A company that does not exist in the organization is a 400 with param companyId." }, "tags": { "description": "Replaces the whole list.", "type": "array", "items": { "type": "string", "pattern": "^[^\\s,][^,]{0,48}$" }, "maxItems": 20 }, "fields": { "type": "object", "additionalProperties": true, "example": { "plan": "pro", "segment": null }, "description": "Values for the contact fields you created with POST /v2/contact-fields, by key. The keys you omit stay as they were; null removes the value. Each value is checked against the type of its field. Nothing is saved if one key or value is not accepted." } } }, "ContactFieldOption": { "type": "object", "properties": { "value": { "type": "string", "example": "pro", "maxLength": 80, "minLength": 1 }, "label": { "type": "string", "example": "Pro", "description": "What people see. Defaults to the value.", "maxLength": 80 } }, "required": [ "value" ] }, "CreateContactField": { "type": "object", "properties": { "key": { "type": "string", "example": "plan", "description": "Letters, numbers and underscores, starting with a letter. Unique in the organization and fixed once created.", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,63}$" }, "type": { "type": "string", "enum": [ "text", "textarea", "email", "phone", "url", "number", "date", "boolean", "select" ], "description": "The kind of value it holds. Values are checked against it: email, phone, url, number, date (YYYY-MM-DD), boolean, select (one of the options) or free text." }, "label": { "type": "string", "example": "Plan", "description": "Defaults to the key.", "maxLength": 255, "minLength": 1 }, "options": { "description": "Required for type select and not allowed for the others.", "type": "array", "items": { "$ref": "#/components/schemas/ContactFieldOption" }, "maxItems": 500 } }, "required": [ "key", "type" ] }, "ContactFieldOptionOut": { "type": "object", "properties": { "value": { "type": "string", "example": "pro" }, "label": { "type": "string", "example": "Pro" } }, "required": [ "value", "label" ] }, "ContactField": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "contact_field" ] }, "id": { "type": "string", "example": "cfd_7AdX2mRw0TqS9mYp3LkQ8d" }, "key": { "type": "string", "example": "plan" }, "label": { "type": "string", "example": "Plan" }, "type": { "type": "string", "enum": [ "text", "textarea", "email", "phone", "url", "number", "date", "boolean", "select" ] }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/ContactFieldOptionOut" } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "key", "label", "type", "options", "createdAt", "updatedAt" ] }, "ContactFieldList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactField" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateContactField": { "type": "object", "properties": { "label": { "type": "string", "example": "Plan contratado", "maxLength": 255, "minLength": 1 }, "options": { "description": "Replaces the options of a select field. Contacts keep the values they already have.", "type": "array", "items": { "$ref": "#/components/schemas/ContactFieldOption" }, "maxItems": 500 } } }, "CreateCompany": { "type": "object", "properties": { "name": { "type": "string", "example": "Panadería La Espiga", "maxLength": 255, "minLength": 1 }, "rut": { "type": "string", "example": "76.123.456-7", "description": "Unique among the live companies of the organization.", "maxLength": 20, "minLength": 1 }, "type": { "type": "string", "enum": [ "prospect", "client", "partner", "vendor" ], "default": "prospect" }, "status": { "type": "string", "enum": [ "lead", "active", "paused", "lost" ], "default": "lead" }, "website": { "type": "string", "example": "laespiga.cl", "maxLength": 255 }, "industry": { "type": "string", "example": "Food", "maxLength": 120, "minLength": 1 }, "source": { "type": "string", "example": "referral", "maxLength": 50, "minLength": 1 }, "notes": { "type": "string", "example": "Buys flour every week.", "maxLength": 2000 } }, "required": [ "name" ] }, "CompanyDetail": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string", "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Panadería La Espiga" }, "rut": { "type": [ "string", "null" ], "example": "76.123.456-7" }, "type": { "type": "string", "enum": [ "prospect", "client", "partner", "vendor" ], "description": "What the company is for the organization." }, "status": { "type": "string", "enum": [ "lead", "active", "paused", "lost" ], "description": "How the relationship is today." }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "contactIds": { "example": [ "ctc_4Zq0x8bVw1TqS9mYp3RkLd" ], "description": "The people of this company, as contact ids.", "type": "array", "items": { "type": "string" } } }, "required": [ "object", "id", "name", "rut", "type", "status", "website", "industry", "source", "notes", "createdAt", "updatedAt", "contactIds" ] }, "Company": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "company" ] }, "id": { "type": "string", "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Panadería La Espiga" }, "rut": { "type": [ "string", "null" ], "example": "76.123.456-7" }, "type": { "type": "string", "enum": [ "prospect", "client", "partner", "vendor" ], "description": "What the company is for the organization." }, "status": { "type": "string", "enum": [ "lead", "active", "paused", "lost" ], "description": "How the relationship is today." }, "website": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "rut", "type", "status", "website", "industry", "source", "notes", "createdAt", "updatedAt" ] }, "CompanyList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateCompany": { "type": "object", "properties": { "name": { "type": "string", "example": "Panadería La Espiga", "maxLength": 255, "minLength": 1 }, "rut": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 20, "minLength": 1 }, "type": { "type": "string", "enum": [ "prospect", "client", "partner", "vendor" ] }, "status": { "type": "string", "enum": [ "lead", "active", "paused", "lost" ] }, "website": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 255 }, "industry": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 120, "minLength": 1 }, "source": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 50, "minLength": 1 }, "notes": { "type": [ "string", "null" ], "description": "null removes it.", "maxLength": 2000 } } }, "CreateLeadForm": { "type": "object", "properties": { "name": { "type": "string", "description": "Form name", "example": "Formulario de contacto", "maxLength": 255, "minLength": 1 }, "tags": { "description": "Tags auto-applied to leads", "example": [ "landing", "contacto" ], "type": "array", "items": { "type": "string", "maxLength": 50 } }, "source": { "type": "string", "description": "Source label for the entity", "example": "landing_contacto", "pattern": "^[a-z0-9_-]+$", "maxLength": 100 }, "pipelineId": { "type": "string", "example": "ppl_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The pipeline where the leads of this form start. A pipeline that does not exist in the organization is a 400 with param pipelineId." } }, "required": [ "name", "pipelineId" ] }, "LeadFormWithSecret": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "example": "lfm_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Contacto web" }, "pipelineId": { "type": "string", "example": "ppl_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The pipeline where the leads of this form start." }, "tags": { "example": [ "landing" ], "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "example": "landing_contacto" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "An inactive form does not accept leads." }, "keyPrefix": { "type": "string", "example": "a1b2c3d4e5f6", "description": "The first characters of the key, to tell which key a website has. It is not the key." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "The key the website sends with each lead. It is shown only here; keep it." } }, "required": [ "object", "id", "name", "pipelineId", "tags", "source", "status", "keyPrefix", "createdAt", "updatedAt", "secret" ] }, "LeadForm": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "lead_form" ] }, "id": { "type": "string", "example": "lfm_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Contacto web" }, "pipelineId": { "type": "string", "example": "ppl_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The pipeline where the leads of this form start." }, "tags": { "example": [ "landing" ], "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "example": "landing_contacto" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "An inactive form does not accept leads." }, "keyPrefix": { "type": "string", "example": "a1b2c3d4e5f6", "description": "The first characters of the key, to tell which key a website has. It is not the key." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "pipelineId", "tags", "source", "status", "keyPrefix", "createdAt", "updatedAt" ] }, "LeadFormList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadForm" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateLeadForm": { "type": "object", "properties": { "name": { "type": "string", "description": "Form name", "maxLength": 255, "minLength": 1 }, "tags": { "description": "Tags auto-applied to leads", "type": "array", "items": { "type": "string", "maxLength": 50 } }, "source": { "type": "string", "description": "Source label", "pattern": "^[a-z0-9_-]+$", "maxLength": 100 }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "pipelineId": { "type": "string", "example": "ppl_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Moves the form to another pipeline. A pipeline that does not exist in the organization is a 400 with param pipelineId." } } }, "SuppressionInventoryStore": { "type": "object", "properties": { "id": { "type": "string", "example": "conversation_messages" }, "store": { "type": "string", "enum": [ "table", "object-store" ] }, "rows": { "type": "number" } }, "required": [ "id", "store", "rows" ] }, "SuppressionInventory": { "type": "object", "properties": { "cases": { "type": "number" }, "openCases": { "type": "number", "description": "Open cases. While there are any, the real call needs closeOpenCases=true." }, "files": { "type": "number" }, "stores": { "type": "array", "items": { "$ref": "#/components/schemas/SuppressionInventoryStore" } } }, "required": [ "cases", "openCases", "files", "stores" ] }, "Suppression": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "suppression" ] }, "id": { "type": [ "string", "null" ], "example": "sup_3PqA0x8bVw1TqS9mYp3RkL", "description": "null on a dryRun: nothing was created." }, "contactId": { "type": "string", "example": "ctc_7Hc2LmQ0x8bVw1TqS9mYp3" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "failed", "held", "preview" ] }, "phase": { "type": [ "string", "null" ], "enum": [ "inventory", "rows", "objects", "rest", "done", null ] }, "reason": { "type": "string", "enum": [ "data_subject_request", "controller_instruction" ] }, "legalHold": { "type": "boolean" }, "closedOpenCases": { "type": "number" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Rows erased or anonymized per store. Numbers only." }, "errorCode": { "type": [ "string", "null" ] }, "inventory": { "description": "Only on dryRun: what would be erased, by store, without content.", "anyOf": [ { "$ref": "#/components/schemas/SuppressionInventory" }, { "type": "null" } ] }, "createdAt": { "type": [ "string", "null" ] }, "completedAt": { "type": [ "string", "null" ] }, "dryRun": { "type": "boolean", "description": "Present and true only on a dry run: nothing was erased and the inventory shows what would be." } }, "required": [ "object", "id", "contactId", "status", "phase", "reason", "legalHold", "closedOpenCases", "counts", "errorCode", "inventory", "createdAt", "completedAt" ] }, "InlineContact": { "type": "object", "properties": { "name": { "type": "string", "example": "Ana Pérez", "description": "Required to create. When the contact exists and you omit it, the name stays. A new contact with no name is named after the externalRef.", "maxLength": 255, "minLength": 1 }, "email": { "type": "string", "example": "ana@example.com", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "example": "+56912345678", "maxLength": 50, "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[^\\s,][^,]{0,48}$" }, "maxItems": 20 }, "companyId": { "type": "string", "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The company of the person, used only when the contact is created here. A company that does not exist in the organization is a 400 with param contact.companyId." }, "externalRef": { "type": "string", "example": "crm-4471", "description": "Your own id for this person. The contact with this externalRef is used; if there is none it is created.", "maxLength": 255, "minLength": 1 } } }, "CreateCase": { "oneOf": [ { "type": "object", "title": "contactId", "properties": { "contactId": { "type": "string", "example": "ctc_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The contact of the case. Send this or contact, never both (400 on contact)." }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that attends the case. It needs the api channel (422 agent_channel_disabled otherwise). Alone, the case opens in the pipeline where this agent attends the entry stage; if it attends the entry of more than one pipeline that is 422 on pipelineId, so send pipelineId or stageId too. A copilot (an agent with audience internal) attends no stage: send its pipelineId or stageId, the case answers with the copilot whatever agent the stage has, and email cases are refused." }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ", "description": "The case enters by the entry stage of this pipeline." }, "stageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage where the case starts." }, "channel": { "type": "string", "enum": [ "api", "email" ], "default": "api", "description": "email opens a case you write to by email. The contact needs an email address and the organization a verified sender domain (422 contact_without_email, 422 sender_domain_not_verified). The agent needs the email channel." }, "from": { "type": "string", "example": "support@mail.acme.com", "description": "With channel email, the sender address. It must belong to a verified domain. Defaults to the first verified domain.", "maxLength": 320 } }, "required": [ "contactId" ], "additionalProperties": false, "example": { "contactId": "ctc_02y0e5MANqacVbmtn1YyeJ", "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "pipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ", "channel": "api" } }, { "type": "object", "title": "contact", "properties": { "contact": { "description": "Finds or creates the contact in the same call. It needs externalRef or phone: the contact with that externalRef, or the one whose phone has the same digits, is used; if there is none it is created with the name (default: the externalRef or the phone). A contact that already exists is never changed: use PATCH /v2/contacts/{id}. Send this or contactId, never both.", "type": "object", "properties": { "name": { "type": "string", "example": "Ana Pérez", "description": "Required to create. When the contact exists and you omit it, the name stays. A new contact with no name is named after the externalRef.", "maxLength": 255, "minLength": 1 }, "email": { "type": "string", "example": "ana@example.com", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "phone": { "type": "string", "example": "+56912345678", "maxLength": 50, "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "pattern": "^[^\\s,][^,]{0,48}$" }, "maxItems": 20 }, "companyId": { "type": "string", "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The company of the person, used only when the contact is created here. A company that does not exist in the organization is a 400 with param contact.companyId." }, "externalRef": { "type": "string", "example": "crm-4471", "description": "Your own id for this person. The contact with this externalRef is used; if there is none it is created.", "maxLength": 255, "minLength": 1 } } }, "agentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that attends the case. It needs the api channel (422 agent_channel_disabled otherwise). Alone, the case opens in the pipeline where this agent attends the entry stage; if it attends the entry of more than one pipeline that is 422 on pipelineId, so send pipelineId or stageId too. A copilot (an agent with audience internal) attends no stage: send its pipelineId or stageId, the case answers with the copilot whatever agent the stage has, and email cases are refused." }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ", "description": "The case enters by the entry stage of this pipeline." }, "stageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage where the case starts." }, "channel": { "type": "string", "enum": [ "api", "email" ], "default": "api", "description": "email opens a case you write to by email. The contact needs an email address and the organization a verified sender domain (422 contact_without_email, 422 sender_domain_not_verified). The agent needs the email channel." }, "from": { "type": "string", "example": "support@mail.acme.com", "description": "With channel email, the sender address. It must belong to a verified domain. Defaults to the first verified domain.", "maxLength": 320 } }, "required": [ "contact" ], "additionalProperties": false, "example": { "contact": { "name": "Ana Pérez", "email": "ana@example.com", "externalRef": "crm-4471" }, "agentId": "agt_02y0e5MANqacVbmtn1YyeJ", "pipelineId": "ppl_02y0e5MANqacVbmtn1YyeJ", "channel": "api" } } ] }, "LastMessage": { "type": "object", "properties": { "author": { "type": "string", "enum": [ "contact", "agent", "team" ] }, "type": { "type": "string", "example": "text" }, "text": { "type": [ "string", "null" ], "description": "The first 140 characters. null when the message is a file." } }, "required": [ "author", "type", "text" ] }, "CaseContact": { "type": "object", "properties": { "id": { "type": "string", "example": "ctc_4Zq0x8bVw1TqS9mYp3RkLd" }, "presence": { "$ref": "#/components/schemas/Presence" } }, "required": [ "id", "presence" ] }, "Case": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "case" ] }, "id": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "contactId": { "type": "string", "example": "ctc_4Zq0x8bVw1TqS9mYp3RkLd" }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "stageId": { "type": [ "string", "null" ] }, "agentId": { "type": [ "string", "null" ], "description": "The agent that answers the case: the copilot of a copilot case, otherwise the agent of the current stage." }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "assigneeId": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "whatsapp", "api", "in_app", "email", null ], "description": "Where the contact talks: whatsapp, email, api (your own system) or in_app. null when the case has no channel to write back." }, "phoneNumberId": { "type": [ "string", "null" ], "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The WhatsApp number the contact wrote to, when it is a WhatsApp case." }, "control": { "type": "string", "enum": [ "agent", "human" ], "description": "Who answers the contact. human also covers a case the agent escalated and nobody took yet: see agentState." }, "agentState": { "type": "string", "enum": [ "idle", "thinking", "replying", "waiting_for_contact", "escalated" ], "description": "What the agent is doing, to drive a typing indicator: thinking and replying mean it is working; waiting_for_contact means it answered; escalated means it asked for a person; idle is everything else." }, "unread": { "type": "integer", "description": "Messages of the contact since the last POST /v2/cases/{id}/read." }, "lastMessageAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastMessage": { "description": "A preview of the last public message.", "anyOf": [ { "$ref": "#/components/schemas/LastMessage" }, { "type": "null" } ] }, "contact": { "description": "The contact with its presence. Present only on GET /v2/cases and GET /v2/cases/{id}, when the organization setting presenceEnabled is on, at least one presence signal has arrived, and the key has the contacts:presence-read scope.", "type": "object", "properties": { "id": { "type": "string", "example": "ctc_4Zq0x8bVw1TqS9mYp3RkLd" }, "presence": { "$ref": "#/components/schemas/Presence" } }, "required": [ "id", "presence" ] }, "outcome": { "type": [ "string", "null" ] }, "closedAt": { "type": [ "string", "null" ], "format": "date-time" }, "fields": { "type": "object", "additionalProperties": true, "description": "The values of the fields the pipeline declares, by key. Sensitive fields are not included." }, "tags": { "description": "The tags of the contact of the case.", "type": "array", "items": { "type": "string" } }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the case was archived: out of the board, state untouched. null when it is on the board." }, "muted": { "type": "boolean", "description": "true while the contact is muted: the agent does not answer them and their open cases are closed. Muting belongs to the person, so every case of the contact shows it." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "contactId", "pipelineId", "stageId", "agentId", "status", "assigneeId", "channel", "phoneNumberId", "control", "agentState", "unread", "lastMessageAt", "lastMessage", "outcome", "closedAt", "fields", "tags", "archivedAt", "muted", "createdAt", "updatedAt" ] }, "CaseList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Case" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateCase": { "type": "object", "properties": { "fields": { "type": "object", "additionalProperties": true, "example": { "address": "Av. Siempre Viva 742" }, "description": "Values for fields the pipeline declares, by key, whoever fills them (team, channel, system or agent). A field marked sensitive is written but never returned: read it with POST /v2/cases/{id}/fields/{key}/reveal. Nothing is saved if one key is not accepted." }, "tags": { "example": [ "vip", "rm" ], "description": "Replaces the tags of the case. Tags belong to the contact: the contact shows the same list, and so does every other case of the person.", "type": "array", "items": { "type": "string", "pattern": "^[^\\s,][^,]{0,48}$" }, "maxItems": 20 } } }, "MoveCase": { "type": "object", "properties": { "stageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage to move to. A stage of another pipeline moves the case to that pipeline and needs the cases:reorganize scope. Send this or pipelineId, never both." }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ", "description": "Moves the case to the entry stage of this pipeline and needs the cases:reorganize scope. Send this or stageId, never both." } } }, "AssignCase": { "type": "object", "properties": { "assigneeId": { "type": [ "string", "null" ], "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "An active member who can attend cases. null unassigns." } }, "required": [ "assigneeId" ] }, "CloseCase": { "type": "object", "properties": { "outcome": { "type": "string", "example": "resolved", "description": "Why it closed. Up to 50 characters.", "maxLength": 50, "minLength": 1 } } }, "QueuedCase": { "type": "object", "properties": { "id": { "type": "string", "example": "case_4Zq0x8bVw1TqS9mYp3RkLd" }, "contactName": { "type": [ "string", "null" ] }, "pipelineId": { "type": "string", "example": "pln_4Zq0x8bVw1TqS9mYp3RkLd" }, "pipelineName": { "type": "string" }, "stageId": { "type": [ "string", "null" ] }, "stageName": { "type": [ "string", "null" ] }, "assigneeId": { "type": [ "string", "null" ] }, "since": { "type": "string", "format": "date-time", "description": "When the wait started." }, "waitMinutes": { "type": "integer", "description": "Minutes of attention waited: only the time inside the business hours of the pipeline counts." }, "waitColor": { "type": [ "string", "null" ], "enum": [ "green", "yellow", "red", null ], "description": "Green, yellow or red by the wait thresholds of the pipeline. Only the cases waiting for a person carry it." } }, "required": [ "id", "contactName", "pipelineId", "pipelineName", "stageId", "stageName", "assigneeId", "since", "waitMinutes" ] }, "CaseQueue": { "type": "object", "properties": { "object": { "type": "string", "example": "case_queue" }, "memberId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd" }, "waitingForPerson": { "description": "Cases the agent handed to a person and nobody took: assigned to the member or without an owner. A case leaves when someone takes it, answers it or it closes.", "type": "array", "items": { "$ref": "#/components/schemas/QueuedCase" } }, "waitingForReply": { "description": "Cases the member escalated, sitting in a stage with attentionRole escalation, still without an answer.", "type": "array", "items": { "$ref": "#/components/schemas/QueuedCase" } }, "answered": { "description": "Cases back in a stage with attentionRole answer whose customer has not been answered yet.", "type": "array", "items": { "$ref": "#/components/schemas/QueuedCase" } } }, "required": [ "object", "memberId", "waitingForPerson", "waitingForReply", "answered" ] }, "MoveCasesBatch": { "type": "object", "properties": { "caseIds": { "example": [ "cse_4Zq0x8bVw1TqS9mYp3RkLd" ], "description": "Up to 100 cases of one pipeline.", "type": "array", "items": { "type": "string" }, "maxItems": 100, "minItems": 1 }, "stageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage they move to. The cases have to be in the pipeline of this stage: to change pipeline use POST /v2/cases/{id}/move." } }, "required": [ "caseIds", "stageId" ] }, "NotMovedCase": { "type": "object", "properties": { "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "reason": { "type": "string", "enum": [ "not_found", "not_in_pipeline", "archived", "closed", "already_in_stage", "required_fields_missing" ], "description": "not_found: no such case. not_in_pipeline: the case is in another pipeline. archived or closed: it cannot move. already_in_stage: nothing to do. required_fields_missing: the stage requires fields the case lacks, named in missingFields." }, "missingFields": { "description": "With required_fields_missing, the keys of the fields.", "type": "array", "items": { "type": "string" } } }, "required": [ "caseId", "reason" ] }, "CaseBatchMove": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "case_batch_move" ] }, "moved": { "type": "integer", "description": "Cases that changed stage." }, "notMoved": { "type": "array", "items": { "$ref": "#/components/schemas/NotMovedCase" } } }, "required": [ "object", "moved", "notMoved" ] }, "MuteCase": { "type": "object", "properties": { "reason": { "type": "string", "example": "Sends spam", "maxLength": 200, "description": "Why. It is saved with the contact.", "minLength": 1 } } }, "EscalateCase": { "type": "object", "properties": { "reason": { "type": "string", "example": "The person asked to talk to someone", "maxLength": 500, "description": "Why the case needs a person. Your team sees it.", "minLength": 1 } }, "required": [ "reason" ] }, "RevealedCaseField": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "revealed_case_field" ] }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "key": { "type": "string", "example": "bank_account" }, "value": { "type": [ "string", "null" ], "description": "The value as saved. null when the field has no value yet." } }, "required": [ "object", "caseId", "key", "value" ] }, "ContactEventSent": { "type": "object", "properties": { "triggerId": { "type": "string" }, "whatsappMessageId": { "type": [ "string", "null" ] }, "emailMessageId": { "type": [ "string", "null" ] } }, "required": [ "triggerId", "whatsappMessageId", "emailMessageId" ] }, "ContactEventCaseAction": { "type": "object", "properties": { "triggerId": { "type": "string" }, "action": { "type": "string", "enum": [ "opened", "moved", "unchanged", "none" ] }, "caseId": { "type": [ "string", "null" ] } }, "required": [ "triggerId", "action", "caseId" ] }, "ContactEvent": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "contact_event" ] }, "id": { "type": "string", "example": "cev_02y0e5MANqacVbmtn1YyeJ" }, "type": { "type": "string" }, "contactId": { "type": "string" }, "result": { "type": "string", "enum": [ "sent", "skipped" ] }, "sent": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEventSent" } }, "caseActions": { "description": "What each matching trigger with onEvent did to the case of the contact: opened a new case, moved the open one, left it where it was (unchanged), or found no open case to move (none). Empty when no trigger has onEvent.", "type": "array", "items": { "$ref": "#/components/schemas/ContactEventCaseAction" } }, "reason": { "type": [ "string", "null" ], "description": "Why nothing was sent: null when the matching triggers only act on the case and have no message, no_trigger, opted_out, no_phone, template_not_approved, human_in_control, cooldown, no_whatsapp_number, not_allowed or missing_variable. Cadence triggers add cadence_active (the contact is already in this cadence) and outside_window (the first attempt waits for the next window). Email triggers add no_email, recipient_not_allowed, no_verified_domain and open_case_elsewhere." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "type", "contactId", "result", "sent", "caseActions", "reason", "createdAt" ] }, "ContactEventList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactEvent" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateReminder": { "type": "object", "properties": { "title": { "type": "string", "example": "Call back about the quote", "maxLength": 255, "minLength": 1 }, "description": { "type": "string", "maxLength": 2000 }, "type": { "type": "string", "enum": [ "call", "email", "meeting", "follow_up", "task", "other" ], "default": "task" }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ], "default": "medium" }, "dueAt": { "type": "string", "format": "date-time", "example": "2030-01-15T14:00:00.000Z", "description": "When it is due, with the time zone." }, "assigneeId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The member who has to do it. They see it in their tasks and get the notice when it is due." } }, "required": [ "title", "dueAt", "assigneeId" ] }, "Reminder": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "reminder" ] }, "id": { "type": "string", "example": "rem_4Zq0x8bVw1TqS9mYp3RkLd" }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "call", "email", "meeting", "follow_up", "task", "other" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "status": { "type": "string", "enum": [ "pending", "in_progress", "overdue", "completed", "dismissed" ], "description": "pending until someone completes or dismisses it. overdue when its time passed and nobody did." }, "dueAt": { "type": "string", "format": "date-time" }, "assigneeId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "completionNote": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "title", "description", "type", "priority", "status", "dueAt", "assigneeId", "completedAt", "completionNote", "createdAt", "updatedAt" ] }, "ReminderList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Reminder" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateReminder": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "minLength": 1 }, "description": { "type": "string", "maxLength": 2000 }, "type": { "type": "string", "enum": [ "call", "email", "meeting", "follow_up", "task", "other" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "urgent" ] }, "dueAt": { "type": "string", "format": "date-time" }, "assigneeId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Reassigns it. A reminder tied to a meeting made in the dashboard cannot be reassigned: 400 on assigneeId." } } }, "CompleteReminder": { "type": "object", "properties": { "completionNote": { "type": "string", "maxLength": 2000, "description": "What happened. It is saved with the reminder." } } }, "PresenceSignal": { "type": "object", "properties": { "externalRef": { "type": "string", "example": "crm-4471", "description": "The externalRef you set on the contact. A reference that matches no contact of this organization is ignored.", "maxLength": 255, "minLength": 1 }, "state": { "type": "string", "enum": [ "active", "offline" ], "description": "active: the person is in your app right now, send it about every 60 seconds while they are. offline: they left; they stop showing as online at once." } }, "required": [ "externalRef", "state" ] }, "ReportPresenceSignals": { "type": "object", "properties": { "signals": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "$ref": "#/components/schemas/PresenceSignal" } } }, "required": [ "signals" ] }, "PresenceSignalsResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "presence_signals_result" ] }, "accepted": { "type": "number", "description": "How many signals matched a contact of this organization. It does not say which ones did not." } }, "required": [ "object", "accepted" ] }, "PresenceSettings": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "presence_settings" ] }, "enabled": { "type": "boolean", "description": "The organization setting presenceEnabled. Presence shows only when it is true and hasSignals is true." }, "hasSignals": { "type": "boolean", "description": "True once at least one signal arrived through POST /v2/presence-signals." } }, "required": [ "object", "enabled", "hasSignals" ] }, "UpdatePresenceSettings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true shows online and last seen in contacts and cases and allows presence=online. false hides them. Signals keep being stored while it is off." } }, "required": [ "enabled" ] }, "Organization": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "organization" ] }, "id": { "type": "string", "example": "org_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Panadería Ana" }, "slug": { "type": "string", "example": "panaderia-ana" } }, "required": [ "object", "id", "name", "slug" ] }, "OrganizationBusinessHours": { "type": "object", "properties": { "timezone": { "type": "string", "example": "America/Santiago" }, "startHour": { "type": "number", "minimum": 0, "maximum": 23, "example": 9 }, "endHour": { "type": "number", "minimum": 0, "maximum": 23, "example": 18 }, "activeSaturday": { "type": "boolean" }, "activeSunday": { "type": "boolean" } }, "required": [ "timezone", "startHour", "endHour", "activeSaturday", "activeSunday" ] }, "OrganizationSettings": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "organization_settings" ] }, "businessHours": { "description": "When the human team attends. Null until it is set. An agent in a stage set to answer outside business hours answers only outside this window.", "anyOf": [ { "$ref": "#/components/schemas/OrganizationBusinessHours" }, { "type": "null" } ] }, "cerrarTrasDiasSinActividad": { "type": [ "number", "null" ], "description": "Days of silence after which a conversation closes by itself. Null means it never closes by inactivity. Until it is set, the house default applies." }, "presenceEnabled": { "type": "boolean", "description": "Whether presence shows. Same setting as /v2/presence/settings." }, "noPersistTraces": { "type": "boolean", "description": "While true, the traces of the agent turns are not stored." }, "branding": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Public branding of the organization: logo, color and links." } }, "required": [ "object", "businessHours", "cerrarTrasDiasSinActividad", "presenceEnabled", "noPersistTraces", "branding" ] }, "CompanyProfile": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "company_profile" ] }, "businessName": { "type": "string" }, "businessDescription": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "website": { "type": "string" }, "schedule": { "type": "string" }, "services": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } } }, "faq": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "answer": { "type": "string" } } } }, "customInstructions": { "type": "string" } }, "required": [ "object" ] }, "CreateNote": { "type": "object", "properties": { "content": { "type": "string", "example": "Call back on Monday.", "maxLength": 10000, "minLength": 1 }, "authorName": { "type": "string", "example": "Ana Pérez", "maxLength": 120, "description": "The person who writes the note, shown as its author. Omit it to sign with the name of the API key.", "minLength": 1 } }, "required": [ "content" ] }, "Note": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "note" ] }, "id": { "type": "string", "example": "not_4Zq0x8bVw1TqS9mYp3RkLd" }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "content": { "type": "string" }, "author": { "type": [ "string", "null" ], "description": "Who wrote it: authorName, a member, or the name of the API key." }, "pinned": { "type": "boolean", "description": "true for the pinned note of the case, shown first." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "content", "author", "pinned", "createdAt", "updatedAt" ] }, "NoteList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateNote": { "type": "object", "properties": { "content": { "type": "string", "example": "Call back on Tuesday.", "maxLength": 10000, "minLength": 1 }, "pinned": { "type": "boolean", "description": "true pins the note and unpins the one that was pinned: a case has one pinned note. false unpins it. Send content, pinned or both." } } }, "Attachment": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "attachment" ] }, "id": { "type": "string", "example": "att_4Zq0x8bVw1TqS9mYp3RkLd" }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "filename": { "type": "string", "example": "contract.pdf" }, "mimeType": { "type": "string", "example": "application/pdf" }, "sizeBytes": { "type": "integer" }, "source": { "type": "string", "enum": [ "manual", "whatsapp", "note" ], "description": "manual is uploaded by API or by the team." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "filename", "mimeType", "sizeBytes", "source", "createdAt" ] }, "AttachmentList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AttachmentDownload": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "attachment_download" ] }, "url": { "type": "string", "description": "A signed link. Open it before expiresAt." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "url", "expiresAt" ] }, "File": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "file" ] }, "id": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Use it as fileId in a message, a campaign or a template header." }, "purpose": { "type": "string", "enum": [ "message_media", "template_header", "campaign_media" ], "description": "What the file is for. message_media: the image, video or document of one WhatsApp message. campaign_media: the same, for a campaign. template_header: the sample file WhatsApp reviews in a template header. The purpose sets which types and sizes are accepted, and a file only works where its purpose says." }, "filename": { "type": "string", "example": "promo.jpg" }, "mimeType": { "type": "string", "example": "image/jpeg", "description": "The type found in the content, not the one the client sent." }, "sizeBytes": { "type": "integer", "example": 184320 }, "sha256": { "type": "string", "example": "a3f1c0d2e4b5a6978877665544332211a3f1c0d2e4b5a6978877665544332211", "description": "SHA-256 of the content, in hex." }, "contactId": { "type": [ "string", "null" ], "example": null, "description": "The contact the file is about, or null." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "purpose", "filename", "mimeType", "sizeBytes", "sha256", "contactId", "createdAt" ] }, "FileList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "MessageAttachment": { "type": "object", "properties": { "type": { "type": "string", "example": "image" }, "mimeType": { "type": "string", "example": "image/png" }, "url": { "type": "string", "description": "A signed link. Open it before expiresAt." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "mimeType", "url", "expiresAt" ] }, "InteractiveButton": { "type": "object", "properties": { "id": { "type": "string", "example": "appt:1:confirm", "maxLength": 256, "description": "Comes back as reply.id when the person taps it. Unique within the message." }, "title": { "type": "string", "example": "Confirm", "maxLength": 20 } }, "required": [ "id", "title" ] }, "InteractiveRow": { "type": "object", "properties": { "id": { "type": "string", "example": "tue-10", "maxLength": 200 }, "title": { "type": "string", "example": "Tuesday", "maxLength": 24 }, "description": { "type": "string", "example": "10:00", "maxLength": 72 } }, "required": [ "id", "title" ] }, "InteractiveSection": { "type": "object", "properties": { "title": { "type": "string", "example": "This week", "maxLength": 24, "description": "Required when the list has more than one section." }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/InteractiveRow" } } }, "required": [ "rows" ] }, "InteractiveList": { "type": "object", "properties": { "button": { "type": "string", "example": "See days", "maxLength": 24, "description": "The label of the button that opens the list." }, "sections": { "description": "Up to 10 sections and 10 rows in total.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveSection" } } }, "required": [ "button", "sections" ] }, "InteractiveProduct": { "type": "object", "properties": { "catalogId": { "type": "string", "example": "1234567890", "description": "The id of the catalog connected to the WhatsApp number." }, "productId": { "type": "string", "example": "sku-1", "description": "The product id in the catalog (content_id / retailer id), not a Lelemon id." } }, "required": [ "catalogId", "productId" ] }, "InteractiveProductSection": { "type": "object", "properties": { "title": { "type": "string", "example": "Cakes", "maxLength": 24 }, "productIds": { "example": [ "sku-1", "sku-2" ], "type": "array", "items": { "type": "string" } } }, "required": [ "title", "productIds" ] }, "InteractiveProducts": { "type": "object", "properties": { "catalogId": { "type": "string", "example": "1234567890" }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveProductSection" } } }, "required": [ "catalogId", "sections" ] }, "InteractiveCatalog": { "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the catalog message." } } }, "InteractiveMediaHeader": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document" ] }, "url": { "type": "string", "example": "https://cdn.example.com/order.jpg", "description": "A public https link WhatsApp can download." } }, "required": [ "type", "url" ] }, "InteractiveCta": { "type": "object", "properties": { "displayText": { "type": "string", "example": "Pay now", "maxLength": 20, "description": "The label of the button that opens the link." }, "url": { "type": "string", "example": "https://shop.example.com/pay/ord_1", "description": "A public https link. It opens in the browser of the person." } }, "required": [ "displayText", "url" ] }, "InteractiveFlow": { "type": "object", "properties": { "flowId": { "type": "string", "example": "1197715005513101", "description": "The id of a published WhatsApp Flow of the account." }, "cta": { "type": "string", "example": "Book now", "maxLength": 20, "description": "The label of the button that opens the Flow." }, "action": { "type": "string", "enum": [ "navigate", "data_exchange" ], "description": "navigate opens the screen you name in screen (the default). data_exchange asks your Flow endpoint for the first screen." }, "screen": { "type": "string", "example": "BOOKING", "description": "The id of the first screen. Required when you send data." }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen starts with." }, "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer. Without it, the platform uses the flowId." } }, "required": [ "flowId", "cta" ] }, "InteractiveCall": { "type": "object", "properties": { "displayText": { "type": "string", "example": "Call support", "maxLength": 20, "description": "The label of the call button. WhatsApp uses \"Call Now\"." }, "ttlMinutes": { "type": "integer", "example": 1440, "minimum": 1, "maximum": 43200, "description": "Minutes the button stays active. WhatsApp uses 10080 (7 days)." }, "payload": { "type": "string", "example": "order-4471", "maxLength": 512, "description": "Comes back with the call, to know which message it came from." } } }, "InteractiveCardHeader": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "url": { "type": "string", "example": "https://cdn.example.com/chair.jpg" } }, "required": [ "type", "url" ] }, "InteractiveCard": { "type": "object", "properties": { "header": { "$ref": "#/components/schemas/InteractiveCardHeader" }, "body": { "type": "string", "maxLength": 160, "description": "Up to 160 characters and 2 line breaks." }, "cta": { "description": "A link button. Send cta or buttons, never both. All cards use the same kind.", "type": "object", "properties": { "displayText": { "type": "string", "example": "Pay now", "maxLength": 20, "description": "The label of the button that opens the link." }, "url": { "type": "string", "example": "https://shop.example.com/pay/ord_1", "description": "A public https link. It opens in the browser of the person." } }, "required": [ "displayText", "url" ] }, "buttons": { "description": "Quick replies. Every card has the same number of buttons and the ids are unique in the message.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveButton" } } }, "required": [ "header" ] }, "InteractiveCarousel": { "type": "object", "properties": { "cards": { "description": "Between 2 and 10 cards, in the order the person swipes them.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveCard" } } }, "required": [ "cards" ] }, "Interactive": { "oneOf": [ { "$ref": "#/components/schemas/InteractiveButtonsMessage" }, { "$ref": "#/components/schemas/InteractiveListMessage" }, { "$ref": "#/components/schemas/InteractiveProductMessage" }, { "$ref": "#/components/schemas/InteractiveProductListMessage" }, { "$ref": "#/components/schemas/InteractiveCatalogMessage" }, { "$ref": "#/components/schemas/InteractiveCtaUrlMessage" }, { "$ref": "#/components/schemas/InteractiveFlowMessage" }, { "$ref": "#/components/schemas/InteractiveLocationRequestMessage" }, { "$ref": "#/components/schemas/InteractiveContactRequestMessage" }, { "$ref": "#/components/schemas/InteractiveCallMessage" }, { "$ref": "#/components/schemas/InteractiveCarouselMessage" } ], "discriminator": { "propertyName": "type", "mapping": { "buttons": "#/components/schemas/InteractiveButtonsMessage", "list": "#/components/schemas/InteractiveListMessage", "product": "#/components/schemas/InteractiveProductMessage", "product_list": "#/components/schemas/InteractiveProductListMessage", "catalog": "#/components/schemas/InteractiveCatalogMessage", "cta_url": "#/components/schemas/InteractiveCtaUrlMessage", "flow": "#/components/schemas/InteractiveFlowMessage", "location_request": "#/components/schemas/InteractiveLocationRequestMessage", "contact_request": "#/components/schemas/InteractiveContactRequestMessage", "call": "#/components/schemas/InteractiveCallMessage", "carousel": "#/components/schemas/InteractiveCarouselMessage" } } }, "MessageReply": { "type": "object", "properties": { "id": { "type": "string", "example": "appt:1:confirm" }, "title": { "type": "string", "example": "Confirm" } }, "required": [ "id", "title" ] }, "MessageOrderItem": { "type": "object", "properties": { "productId": { "type": "string", "example": "sku-1" }, "quantity": { "type": "number", "example": 2 }, "price": { "type": "number", "example": 4990, "description": "Unit price, as the catalog has it." }, "currency": { "type": "string", "example": "CLP" } }, "required": [ "productId", "quantity", "price", "currency" ] }, "MessageOrder": { "type": "object", "properties": { "catalogId": { "type": "string", "example": "1234567890" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MessageOrderItem" } } }, "required": [ "catalogId", "items" ] }, "MessageLocation": { "type": "object", "properties": { "latitude": { "type": "number", "example": -33.4489 }, "longitude": { "type": "number", "example": -70.6693 }, "name": { "type": "string", "example": "Home" }, "address": { "type": "string", "example": "Av. Siempre Viva 742" } }, "required": [ "latitude", "longitude" ] }, "MessageFlowResponse": { "type": "object", "properties": { "token": { "type": "string", "example": "case-42", "description": "The token you sent with the Flow, if any." }, "data": { "type": "object", "additionalProperties": true, "description": "The fields the person filled in the last screen of the Flow.", "example": { "date": "2026-11-02", "time": "10:00" } } }, "required": [ "data" ] }, "MessageSharedPhone": { "type": "object", "properties": { "phone": { "type": "string", "example": "+56912345678" }, "waId": { "type": "string", "example": "56912345678" } }, "required": [ "phone" ] }, "MessageContact": { "type": "object", "properties": { "phones": { "type": "array", "items": { "$ref": "#/components/schemas/MessageSharedPhone" } } }, "required": [ "phones" ] }, "MessageError": { "type": "object", "properties": { "code": { "type": [ "number", "null" ], "example": 131026, "description": "The WhatsApp error code when WhatsApp rejected the message. null when the platform stopped it before sending." }, "message": { "type": "string", "example": "Message undeliverable", "description": "Why the message failed." } }, "required": [ "code", "message" ] }, "Message": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "message" ] }, "id": { "type": "string", "example": "msg_4Zq0x8bVw1TqS9mYp3RkLd" }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "author": { "type": "string", "enum": [ "contact", "agent", "team" ] }, "authorName": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "text": { "type": "string" }, "contentType": { "type": "string", "example": "text" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/MessageAttachment" } }, "interactive": { "description": "The buttons, list, product or catalog the message carried. null on any other message.", "anyOf": [ { "$ref": "#/components/schemas/Interactive" }, { "type": "null" } ] }, "reply": { "description": "Set when the person tapped a button or a list row: the id and title they tapped. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageReply" }, { "type": "null" } ] }, "order": { "description": "Set when the person sent a cart from the WhatsApp catalog. text carries their note. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageOrder" }, { "type": "null" } ] }, "location": { "description": "Set when the person shared a location (answering a location_request or on their own). text carries it as a sentence the agent reads. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageLocation" }, { "type": "null" } ] }, "flowResponse": { "description": "Set when the person finished a WhatsApp Flow: the fields they filled in. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageFlowResponse" }, { "type": "null" } ] }, "contact": { "description": "Set when the person shared their phone answering a contact_request. A contact card the person forwards on their own is not kept. null otherwise.", "anyOf": [ { "$ref": "#/components/schemas/MessageContact" }, { "type": "null" } ] }, "error": { "description": "Set when status is failed: why. null on any other status. Read it to know whether to retry, send a template (outside the 24-hour window) or stop.", "anyOf": [ { "$ref": "#/components/schemas/MessageError" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "sent", "delivered", "read", "failed" ], "description": "Delivery to the channel of the case." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "author", "authorName", "visibility", "text", "contentType", "attachments", "status", "createdAt" ] }, "MessageList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateMessage": { "anyOf": [ { "$ref": "#/components/schemas/CreateContactMessage" }, { "$ref": "#/components/schemas/CreateTeamTextMessage" }, { "$ref": "#/components/schemas/CreateTeamInteractiveMessage" }, { "$ref": "#/components/schemas/CreateTeamFilesMessage" } ] }, "TurnTokens": { "type": "object", "properties": { "input": { "type": "integer" }, "output": { "type": "integer" } }, "required": [ "input", "output" ] }, "TurnStep": { "type": "object", "properties": { "tool": { "type": "string", "description": "Name of the tool the agent called. A Lelemon system tool shows its public name (transfer_to_human, save_case_data, send_buttons...), the same one GET /v2/agents/{id}/tools lists. For a tool from an MCP server it is the server slug and the tool name." }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "durationMs": { "type": "integer", "description": "Milliseconds the tool took." }, "input": { "type": "object", "description": "What the agent sent to the tool, with emails, RUTs, phones, cards and secrets masked by shape. Absent when the tool is marked noPersist: those tools leave only status and duration." }, "output": { "type": "string", "description": "What the tool answered, masked the same way and cut at 4000 characters. Absent when the tool is marked noPersist." } }, "required": [ "tool", "status", "durationMs" ] }, "Turn": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "turn" ] }, "id": { "type": "string", "example": "trn_7Hc2LmQ0x8bVw1TqS9mYp3" }, "caseId": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "agentId": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ], "description": "The model that answered the last call of the turn." }, "status": { "type": "string", "enum": [ "completed", "incomplete", "failed" ], "description": "completed: the agent finished by itself. incomplete: it stopped early and delivered a partial answer. failed: it gave no answer." }, "stopReason": { "type": [ "string", "null" ] }, "iterations": { "type": "integer", "description": "Calls to the model in the turn." }, "tokens": { "$ref": "#/components/schemas/TurnTokens" }, "durationMs": { "type": "integer" }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/TurnStep" } }, "omittedSteps": { "type": "integer", "description": "Tool calls that did not fit in steps (up to 50 steps and 64 KB are kept)." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "agentId", "model", "status", "stopReason", "iterations", "tokens", "durationMs", "steps", "omittedSteps", "createdAt" ] }, "TurnList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Turn" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UsageTotals": { "type": "object", "properties": { "turns": { "type": "integer", "description": "Turns the agent took." }, "messages": { "type": "integer", "description": "Replies the agent wrote." }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "conversations": { "type": "integer", "description": "Conversations opened in the range, the unit that is billed. A conversation is a window per case of up to 10 agent turns or 24 hours, whichever comes first; the next turn opens another one." }, "cases": { "type": "integer", "description": "Cases (conversations) in which the agent wrote at least one reply in the range. A case counts once however many replies it has." } }, "required": [ "turns", "messages", "inputTokens", "outputTokens", "conversations", "cases" ] }, "UsageGroup": { "type": "object", "properties": { "turns": { "type": "integer", "description": "Turns the agent took." }, "messages": { "type": "integer", "description": "Replies the agent wrote." }, "inputTokens": { "type": "integer" }, "outputTokens": { "type": "integer" }, "conversations": { "type": "integer", "description": "Conversations opened in this group. Absent with groupBy=model: a conversation is not split by model." }, "cases": { "type": "integer", "description": "Cases in which the agent wrote a reply in this group. A case with replies on two days counts in both, so the groups can add up to more than totals.cases. Absent with groupBy=model: a case is not split by model." }, "day": { "type": "string", "example": "2026-11-01" }, "agentId": { "type": "string", "example": "agt_7Hc2LmQ0x8bVw1TqS9mYp3" }, "model": { "type": "string", "example": "anthropic/claude-sonnet-4.6" }, "subaccountId": { "type": [ "string", "null" ], "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "With groupBy=subaccount. null is the usage of the platform itself, which is not in any subaccount." } }, "required": [ "turns", "messages", "inputTokens", "outputTokens" ] }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "usage" ] }, "from": { "type": "string", "example": "2026-11-01" }, "to": { "type": "string", "example": "2026-11-30" }, "timezone": { "type": "string", "example": "America/Santiago" }, "totals": { "$ref": "#/components/schemas/UsageTotals" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsageGroup" } } }, "required": [ "object", "from", "to", "timezone", "totals", "data" ] }, "CaseMetrics": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "case_metrics" ] }, "caseId": { "type": "string", "example": "cse_4Zq0x8bVw1TqS9mYp3RkLd" }, "pipelineId": { "type": "string", "example": "ppl_02y0e5MANqacVbmtn1YyeJ" }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "control": { "type": "string", "enum": [ "agent", "human" ], "description": "Who has the case now. human also covers a case the agent handed off and nobody took yet." }, "createdAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The first time the agent handed the case to a person." }, "takenAt": { "type": [ "string", "null" ], "format": "date-time", "description": "The first time a person took the case." }, "takenBy": { "type": [ "string", "null" ], "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The member who took it first. null when nobody did, or when it was taken from the phone." }, "closedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was closed. null while it is open." }, "closedBy": { "type": [ "string", "null" ], "enum": [ "agent", "human", "system", null ], "description": "Who closed it: the agent, a person, or the system (inactivity, follow-ups exhausted). null while it is open." }, "resolvedByAgent": { "type": "boolean", "description": "True when the agent closed it without handing it off and without anyone taking it." }, "waitSeconds": { "type": [ "integer", "null" ], "description": "Seconds between the last handoff and the first time a person took the case. null when it was never handed off and taken." }, "agentSeconds": { "type": "integer", "description": "Seconds the agent attended the case." }, "humanSeconds": { "type": "integer", "description": "Seconds a person attended the case." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The last change. It is the field the range filters by." } }, "required": [ "object", "caseId", "pipelineId", "status", "control", "createdAt", "escalatedAt", "takenAt", "takenBy", "closedAt", "closedBy", "resolvedByAgent", "waitSeconds", "agentSeconds", "humanSeconds", "updatedAt" ] }, "CaseMetricsList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CaseMetrics" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateBudget": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "organization", "subaccount", "agent", "contact" ] }, "subjectId": { "type": "string", "example": "agt_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "Required for subaccount (sub_), agent (agt_) and contact (ctc_). Not allowed for organization. A subaccount budget needs the platform key without Lelemon-Subaccount; the key of the subaccount cannot see or raise it.", "maxLength": 64 }, "monthlyLimitConversations": { "type": "integer", "example": 500, "minimum": 1, "maximum": 10000000, "description": "Monthly limit in conversations. A conversation is a window per case of up to 10 agent turns or 24 hours, whichever comes first." }, "alertPercent": { "type": "integer", "minimum": 1, "maximum": 100, "default": 80 }, "enforcement": { "type": "string", "enum": [ "stop", "notify" ], "default": "stop" } }, "required": [ "scope", "monthlyLimitConversations" ] }, "BudgetPeriod": { "type": "object", "properties": { "start": { "type": "string", "example": "2026-11-01", "description": "First day of the month." }, "resetsAt": { "type": "string", "format": "date-time", "description": "When the month ends and the spent amount goes back to zero." } }, "required": [ "start", "resetsAt" ] }, "Budget": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "budget" ] }, "id": { "type": "string", "example": "bgt_7Hc2LmQ0x8bVw1TqS9mYp3" }, "scope": { "type": "string", "enum": [ "organization", "subaccount", "agent", "contact" ], "description": "What the budget covers: the whole organization, one subaccount, one agent or one contact." }, "subjectId": { "type": [ "string", "null" ], "description": "The sub_, agt_ or ctc_ id the budget covers. null for the organization." }, "monthlyLimitConversations": { "type": "integer", "example": 500, "description": "Monthly limit in conversations." }, "alertPercent": { "type": "integer", "example": 80, "description": "Percent of the limit that fires budget.threshold_reached." }, "enforcement": { "type": "string", "enum": [ "stop", "notify" ], "description": "stop: at the limit the agent stops and the API answers 402 budget_exceeded. notify: the agent keeps working and only the events fire." }, "usedConversations": { "type": "integer", "example": 124, "description": "Conversations used this month." }, "state": { "type": "string", "enum": [ "ok", "alert", "limit_reached" ], "description": "ok: under the alert percent. alert: past it. limit_reached: the used conversations reached the limit." }, "period": { "$ref": "#/components/schemas/BudgetPeriod" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "scope", "subjectId", "monthlyLimitConversations", "alertPercent", "enforcement", "usedConversations", "state", "period", "createdAt", "updatedAt" ] }, "BudgetList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Budget" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateBudget": { "type": "object", "properties": { "monthlyLimitConversations": { "type": "integer", "minimum": 1, "maximum": 10000000, "description": "New monthly limit in conversations. Raising it makes a stopped agent answer again at once and re-arms the alert." }, "alertPercent": { "type": "integer", "minimum": 1, "maximum": 100 }, "enforcement": { "type": "string", "enum": [ "stop", "notify" ] } } }, "Member": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "member" ] }, "id": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The id that POST /v2/cases/{id}/assign takes as assigneeId." }, "name": { "type": [ "string", "null" ], "example": "Ana Pérez" }, "email": { "type": "string", "example": "ana@empresa.cl" }, "role": { "type": "string", "description": "The role of the member. A viewer cannot be assigned cases." }, "availability": { "type": "string", "enum": [ "available", "away" ], "description": "Whether the member is receiving new cases right now." }, "caseScope": { "type": [ "string", "null" ], "enum": [ "all", "unassigned_and_own", "assigned", null ], "description": "Which cases the member sees, when set for them: all (every case of their pipelines), unassigned_and_own (the unassigned ones and theirs) or assigned (only theirs). null means they follow the default of the organization." }, "effectiveCaseScope": { "type": "string", "enum": [ "all", "unassigned_and_own", "assigned" ], "description": "What the member sees now: caseScope, or the default of the organization when that is null. The owner and admins always see all. The MCP connector of Lelemon only works for people who see all." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "email", "role", "availability", "caseScope", "effectiveCaseScope", "createdAt" ] }, "MemberList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "MemberAuditActor": { "type": "object", "properties": { "memberId": { "type": [ "string", "null" ], "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The member who did it, the same id members.list returns." }, "apiKeyId": { "type": [ "string", "null" ], "example": "key_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The API key used. null when it was done from the panel." } }, "required": [ "memberId", "apiKeyId" ] }, "MemberAuditTarget": { "type": "object", "properties": { "memberId": { "type": [ "string", "null" ], "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The member it was done to. null while the person is only invited and has not joined." }, "invitationId": { "type": [ "string", "null" ], "example": "inv_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The invitation it was done to, if the person was invited." }, "email": { "type": [ "string", "null" ], "example": "ana@empresa.cl" } }, "required": [ "memberId", "invitationId", "email" ] }, "MemberAuditEntry": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "member_audit_entry" ] }, "id": { "type": "string", "example": "mae_4Zq0x8bVw1TqS9mYp3RkLd" }, "action": { "type": "string", "enum": [ "invitation.created", "invitation.resent", "invitation.cancelled", "member.role_changed", "member.scope_changed", "member.removed" ] }, "actor": { "$ref": "#/components/schemas/MemberAuditActor" }, "target": { "$ref": "#/components/schemas/MemberAuditTarget" }, "roleBefore": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", "viewer", null ] }, "roleAfter": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", "viewer", null ] }, "scopeBefore": { "type": [ "string", "null" ], "enum": [ "all", "unassigned_and_own", "assigned", null ], "description": "Only in member.scope_changed: the case scope before. null means the default of the organization (and, in other actions, that it does not apply)." }, "scopeAfter": { "type": [ "string", "null" ], "enum": [ "all", "unassigned_and_own", "assigned", null ], "description": "Only in member.scope_changed: the case scope after." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "action", "actor", "target", "roleBefore", "roleAfter", "scopeBefore", "scopeAfter", "createdAt" ] }, "MemberAuditList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MemberAuditEntry" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "MemberAvailability": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "member_availability" ] }, "memberId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd" }, "email": { "type": "string", "example": "ana@empresa.cl" }, "status": { "type": "string", "enum": [ "available", "away" ], "description": "What was marked, by the person or by the API. It does not consider the opening hours of the organization: that is availableForAssignment." }, "availableForAssignment": { "type": "boolean", "description": "Whether the assignment would give this person a new case right now. false if away, and also if available but the organization has opening hours and they are closed: the automatic away by schedule wins, unless the person asked to keep going a while longer (extendedUntil in the future)." }, "changedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the status last changed. null if it never did." }, "extendedUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "Until when the person asked to keep receiving cases after the opening hours. null if there is no extension." } }, "required": [ "object", "memberId", "email", "status", "availableForAssignment", "changedAt", "extendedUntil" ] }, "SetMemberAvailability": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "away" ], "description": "available: can receive new cases. away: the assignment skips them and any extension they asked for is dropped." } }, "required": [ "status" ] }, "UpdateMemberRole": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "The new role. It cannot be above the current role of whoever issued the key, and nobody is named owner by API." } }, "required": [ "role" ] }, "UpdateMemberCaseScope": { "type": "object", "properties": { "caseScope": { "type": [ "string", "null" ], "enum": [ "all", "unassigned_and_own", "assigned", null ], "example": "all", "description": "all: sees every case of their pipelines. unassigned_and_own: the unassigned ones and theirs. assigned: only theirs. null: goes back to the default of the organization." } }, "required": [ "caseScope" ] }, "Invitation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "example": "inv_4Zq0x8bVw1TqS9mYp3RkLd" }, "email": { "type": "string", "example": "soporte@empresa.cl" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "cancelled" ], "description": "pending can still be accepted. expired passed its 7 days: resend it to renew it. accepted already joined. cancelled can no longer be accepted." }, "invitedBy": { "type": [ "string", "null" ], "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The member who invited, the same id members.list returns." }, "invitedAt": { "type": "string", "format": "date-time", "description": "When it was sent. Resending renews it." }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "email", "role", "status", "invitedBy", "invitedAt", "expiresAt" ] }, "InvitationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invitation" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateInvitation": { "type": "object", "properties": { "email": { "type": "string", "example": "soporte@empresa.cl", "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "The owner invites up to admin. An admin invites member or viewer. Nobody invites as owner." } }, "required": [ "email", "role" ] }, "InvitationDelivery": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "invitation" ] }, "id": { "type": "string", "example": "inv_4Zq0x8bVw1TqS9mYp3RkLd" }, "email": { "type": "string", "example": "soporte@empresa.cl" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "status": { "type": "string", "enum": [ "pending", "accepted", "expired", "cancelled" ], "description": "pending can still be accepted. expired passed its 7 days: resend it to renew it. accepted already joined. cancelled can no longer be accepted." }, "invitedBy": { "type": [ "string", "null" ], "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The member who invited, the same id members.list returns." }, "invitedAt": { "type": "string", "format": "date-time", "description": "When it was sent. Resending renews it." }, "expiresAt": { "type": "string", "format": "date-time" }, "emailSent": { "type": "boolean", "description": "false when the email could not be sent. The invitation is created anyway: resend it with invitations.resend or ask the person to check the address. The acceptance link is never returned by the API." } }, "required": [ "object", "id", "email", "role", "status", "invitedBy", "invitedAt", "expiresAt", "emailSent" ] }, "Agenda": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agenda" ] }, "id": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "slug": { "type": "string", "example": "founder", "description": "The short name your team gave the agenda. A filter-friendly label: routes take the id, never the slug." }, "name": { "type": "string", "example": "Founder calls" }, "timezone": { "type": "string", "example": "America/Santiago", "description": "The time zone the opening hours of the agenda are read in." }, "slotDurationMinutes": { "type": "number", "example": 30, "description": "Length of every meeting." }, "minNoticeHours": { "type": "number", "example": 24, "description": "How many hours ahead a slot must start to be offered. Earlier slots are not listed." }, "maxDaysAhead": { "type": "number", "example": 14, "description": "How many days ahead the agenda accepts bookings. It caps daysAhead." }, "bufferBeforeMinutes": { "type": "number", "example": 0, "description": "Free minutes kept before every meeting." }, "bufferAfterMinutes": { "type": "number", "example": 5, "description": "Free minutes kept after every meeting." }, "assignmentStrategy": { "type": "string", "enum": [ "round_robin", "first_available", "least_busy", "specific_member" ], "description": "How a booking picks the team member who takes it." }, "availableHours": { "description": "Opening hours by day of the week, in the time zone of the agenda. A day with no ranges is closed.", "type": "object", "properties": { "monday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "tuesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "wednesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "thursday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "friday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "saturday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "sunday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } } } }, "defaultTitle": { "type": "string", "example": "Reunión" }, "defaultDescription": { "type": [ "string", "null" ] }, "generateMeetLink": { "type": "boolean", "description": "Whether each meeting gets a video call link." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "slug", "name", "timezone", "slotDurationMinutes", "minNoticeHours", "maxDaysAhead", "bufferBeforeMinutes", "bufferAfterMinutes", "assignmentStrategy", "availableHours", "defaultTitle", "defaultDescription", "generateMeetLink", "createdAt", "updatedAt" ] }, "AgendaList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agenda" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateAgenda": { "type": "object", "properties": { "name": { "type": "string", "example": "Founder calls" }, "slug": { "type": "string", "example": "founder", "description": "Short name of the agenda, unique in the organization: lowercase letters, numbers and hyphens. Routes take the id, never the slug." }, "assignmentStrategy": { "type": "string", "enum": [ "round_robin", "first_available", "least_busy", "specific_member" ], "default": "round_robin", "description": "How a booking picks the team member who takes it." }, "timezone": { "type": "string", "example": "America/Santiago", "default": "America/Santiago", "description": "The time zone the opening hours are read in." }, "slotDurationMinutes": { "type": "number", "default": 30, "description": "Length of every meeting." }, "bufferBeforeMinutes": { "type": "number", "default": 0, "description": "Free minutes kept before every meeting." }, "bufferAfterMinutes": { "type": "number", "default": 5, "description": "Free minutes kept after every meeting." }, "minNoticeHours": { "type": "number", "default": 24, "description": "How many hours ahead a slot must start to be offered." }, "maxDaysAhead": { "type": "number", "default": 14, "description": "How many days ahead the agenda accepts bookings." }, "availableHours": { "description": "Opening hours by day of the week, in the time zone of the agenda. A day with no ranges is closed.", "type": "object", "properties": { "monday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "tuesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "wednesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "thursday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "friday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "saturday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "sunday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } } } }, "defaultTitle": { "type": "string", "default": "Reunión" }, "defaultDescription": { "type": "string" }, "generateMeetLink": { "type": "boolean", "default": true } }, "required": [ "name", "slug" ] }, "UpdateAgenda": { "type": "object", "properties": { "name": { "type": "string", "example": "Founder calls" }, "slug": { "type": "string", "example": "founder", "description": "Short name of the agenda, unique in the organization: lowercase letters, numbers and hyphens. Routes take the id, never the slug." }, "assignmentStrategy": { "type": "string", "enum": [ "round_robin", "first_available", "least_busy", "specific_member" ], "default": "round_robin", "description": "How a booking picks the team member who takes it." }, "timezone": { "type": "string", "example": "America/Santiago", "default": "America/Santiago", "description": "The time zone the opening hours are read in." }, "slotDurationMinutes": { "type": "number", "default": 30, "description": "Length of every meeting." }, "bufferBeforeMinutes": { "type": "number", "default": 0, "description": "Free minutes kept before every meeting." }, "bufferAfterMinutes": { "type": "number", "default": 5, "description": "Free minutes kept after every meeting." }, "minNoticeHours": { "type": "number", "default": 24, "description": "How many hours ahead a slot must start to be offered." }, "maxDaysAhead": { "type": "number", "default": 14, "description": "How many days ahead the agenda accepts bookings." }, "availableHours": { "description": "Opening hours by day of the week, in the time zone of the agenda. A day with no ranges is closed.", "type": "object", "properties": { "monday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "tuesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "wednesday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "thursday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "friday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "saturday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } }, "sunday": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaTimeRange" } } } }, "defaultTitle": { "type": "string", "default": "Reunión" }, "defaultDescription": { "type": "string" }, "generateMeetLink": { "type": "boolean", "default": true } } }, "AgendaMember": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "agenda_member" ] }, "id": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The same id that GET /v2/members lists." }, "name": { "type": [ "string", "null" ], "example": "Ana Pérez" }, "calendarConnected": { "type": "boolean", "description": "Whether the person has a connected calendar the agenda can read. Without one the person adds no free slots." }, "active": { "type": "boolean", "description": "Whether the person takes bookings from this agenda. false keeps them in the agenda without offering their slots." }, "priority": { "type": "integer", "example": 1, "description": "Weight when the agenda assigns by priority: higher takes more bookings." } }, "required": [ "object", "id", "name", "calendarConnected", "active", "priority" ] }, "AgendaMemberList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgendaMember" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "AddAgendaMember": { "type": "object", "properties": { "memberId": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "An active member of the organization. List them with GET /v2/members.", "pattern": "^mbr_[0-9A-Za-z]{22}$" }, "priority": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 } }, "required": [ "memberId" ] }, "UpdateAgendaMember": { "type": "object", "properties": { "priority": { "type": "integer", "minimum": 1, "maximum": 1000 }, "active": { "type": "boolean" } } }, "Slot": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "example": "2026-11-03T13:00:00.000Z", "description": "When the slot starts. Send it as start to book it." }, "end": { "type": "string", "format": "date-time", "example": "2026-11-03T13:30:00.000Z" } }, "required": [ "start", "end" ] }, "Availability": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "availability" ] }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "timezone": { "type": "string", "example": "America/Santiago" }, "slots": { "description": "The free slots, nearest first. An empty list means there are none in the window asked.", "type": "array", "items": { "$ref": "#/components/schemas/Slot" } } }, "required": [ "object", "agendaId", "timezone", "slots" ] }, "CreateMeeting": { "type": "object", "properties": { "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01", "description": "The agenda to book in. The one you asked availability for.", "pattern": "^agd_[0-9A-Za-z]{22}$" }, "start": { "type": "string", "format": "date-time", "example": "2026-11-03T13:00:00.000Z", "description": "When it starts, ISO 8601 with a time zone. It must be the start of a slot from the availability of the agenda.", "pattern": "(Z|[+-]\\d{2}:\\d{2})$" }, "attendeeEmail": { "type": "string", "example": "ana@empresa.cl", "description": "Who is booked. The invitation goes to this address.", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "attendeeName": { "type": "string", "example": "Ana Pérez", "maxLength": 120, "minLength": 1 }, "attendeePhone": { "type": "string", "maxLength": 40 }, "companyName": { "type": "string", "maxLength": 200, "description": "Goes into the description of the calendar event." }, "context": { "type": "string", "maxLength": 1000, "description": "What the meeting is for. Goes into the description of the calendar event so whoever attends arrives knowing." } }, "required": [ "agendaId", "start", "attendeeEmail", "attendeeName" ] }, "Meeting": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "example": "mtg_5RvP2aKq9XwLmN3tYbZc01" }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ], "description": "scheduled is a booked meeting. canceled is closed and frees the slot." }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "number", "example": 30 }, "timezone": { "type": "string", "example": "America/Santiago" }, "attendeeEmail": { "type": "string", "example": "ana@empresa.cl" }, "attendeeName": { "type": "string", "example": "Ana Pérez" }, "attendeePhone": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "meetLink": { "type": [ "string", "null" ], "description": "The video call link the attendee got in the invitation." }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the meeting was canceled. null if it was not." }, "cancelReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agendaId", "status", "start", "end", "durationMinutes", "timezone", "attendeeEmail", "attendeeName", "attendeePhone", "companyName", "context", "meetLink", "canceledAt", "cancelReason", "createdAt", "updatedAt" ] }, "MeetingList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Meeting" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CancelMeeting": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Why it is canceled. Stored with the meeting." } } }, "RescheduleMeeting": { "type": "object", "properties": { "start": { "type": "string", "format": "date-time", "example": "2026-11-04T15:00:00.000Z", "description": "The new start, ISO 8601 with a time zone. It must be a free slot of the agenda and the person assigned must be free then.", "pattern": "(Z|[+-]\\d{2}:\\d{2})$" } }, "required": [ "start" ] }, "WebhookEndpointWithSecret": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabledEvents": { "type": "array", "items": { "type": "string" } }, "apiVersion": { "type": "string", "example": "2026-10-29" }, "scope": { "type": "string", "enum": [ "self", "customers" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ], "description": "Why the system turned the endpoint off, when it did." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "example": "whsec_…", "description": "Signing secret. It is shown only here; keep it. Verify with `Lelemon-Signature`." }, "previousSecretExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "After a rotation, until when the previous secret still signs. Both signatures go in the header." } }, "required": [ "object", "id", "url", "description", "enabledEvents", "apiVersion", "scope", "status", "disabledReason", "createdAt", "updatedAt", "secret" ] }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabledEvents": { "type": "array", "items": { "type": "string" } }, "apiVersion": { "type": "string", "example": "2026-10-29" }, "scope": { "type": "string", "enum": [ "self", "customers" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ], "description": "Why the system turned the endpoint off, when it did." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "url", "description", "enabledEvents", "apiVersion", "scope", "status", "disabledReason", "createdAt", "updatedAt" ] }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "WebhookEndpointRotation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "id": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "enabledEvents": { "type": "array", "items": { "type": "string" } }, "apiVersion": { "type": "string", "example": "2026-10-29" }, "scope": { "type": "string", "enum": [ "self", "customers" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "disabledReason": { "type": [ "string", "null" ], "description": "Why the system turned the endpoint off, when it did." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "example": "whsec_…", "description": "The new signing secret. It is shown only here; keep it. Verify with `Lelemon-Signature`. Absent in a dryRun, which rotates nothing." }, "previousSecretExpiresAt": { "type": "string", "format": "date-time", "description": "Until when the previous secret still signs. Both signatures go in the header." } }, "required": [ "object", "id", "url", "description", "enabledEvents", "apiVersion", "scope", "status", "disabledReason", "createdAt", "updatedAt", "previousSecretExpiresAt" ] }, "Event": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types." }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types." } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] }, "WebhookDelivery": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "id": { "type": "string", "example": "whd_3PqA0x8bVw1TqS9mYp3RkL", "description": "Same value the endpoint received in `Lelemon-Delivery-Id`." }, "endpointId": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL" }, "eventId": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "eventType": { "type": "string", "example": "case.escalated" }, "attempt": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "succeeded", "failed", "exhausted" ], "description": "`failed` will be retried. `exhausted` is the last attempt: it is not retried again." }, "httpStatus": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "durationMs": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "endpointId", "eventId", "eventType", "attempt", "status", "httpStatus", "error", "durationMs", "createdAt" ] }, "WebhookDeliveryList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "ResendEvent": { "type": "object", "properties": { "endpointId": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL", "description": "Send only to this endpoint. Without it, to every enabled endpoint subscribed to the event.", "maxLength": 64 } } }, "EventType": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event_type" ] }, "type": { "type": "string", "example": "case.escalated", "enum": [ "case.escalated", "case.closed", "case.stage_entered", "message.created", "case.control_changed", "message.received", "message.human_sent", "message.agent_sent", "case.agent_failed", "case.turn_completed", "budget.threshold_reached", "budget.exceeded", "mcp_server.failed", "message.status_changed", "message.failed", "contact.opted_out", "contact.suppressed", "message.redacted", "approval.requested", "approval.decided", "approval.expired", "approval.escalated", "approval.canceled", "approval.review_requested", "automated_decision.review_requested", "team_question.created", "team_question.answered", "meeting.scheduled", "meeting.rescheduled", "meeting.canceled", "template.status_changed", "campaign.status_changed", "trigger.attempted", "copilot.turn", "run.started", "run.waiting_for_answer", "run.completed", "run.stopped", "run.failed", "run.canceled", "schedule.fired", "schedule.skipped", "schedule.paused", "knowledge_document.ready", "knowledge_document.failed", "phone_number.connected", "phone_number.connection_failed", "phone_number.disconnected", "webhook_endpoint.test" ] }, "description": { "type": "string" }, "data": { "type": "object", "additionalProperties": true, "description": "JSON Schema of the `data` of this event." } }, "required": [ "object", "type", "description", "data" ] }, "EventTypeList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "RecipientAllowlist": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "recipient_allowlist" ] }, "enabled": { "type": "boolean", "description": "While true, nothing is sent to anyone who is not in entries. While false, the list is kept but ignored." }, "entries": { "example": [ "+56912345678", "ana@empresa.cl", "@empresa.cl" ], "description": "Phones in E.164, emails, or whole domains written as @domain. A domain does not include its subdomains.", "type": "array", "items": { "type": "string" } }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "dryRun": { "type": "boolean", "description": "Present and true only on a dry run: the list shown is what would be saved, and nothing was saved." } }, "required": [ "object", "enabled", "entries", "updatedAt" ] }, "ReplaceRecipientAllowlist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "entries": { "maxItems": 1000, "example": [ "+56912345678", "ana@empresa.cl", "@empresa.cl" ], "description": "Replaces the whole list. Phones in E.164 (+56912345678), emails (ana@empresa.cl) or domains (@empresa.cl).", "type": "array", "items": { "type": "string", "maxLength": 320 } } }, "required": [ "enabled", "entries" ] }, "TemplateHeaderInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "image", "video" ], "description": "The media above the body. document: send it with the document field of each message. image and video: send it with components.headerImage or components.headerVideo." }, "exampleFileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files and purpose template_header. WhatsApp reviews it as the sample of the header, and its type must match the header (image, video or document). Send exampleFileId or exampleUrl, one of them. Preferred over a URL." }, "exampleUrl": { "type": "string", "example": "https://files.example.com/sample.pdf", "description": "A public https file Meta reviews as the sample of the header. Lelemon downloads it and uploads it to WhatsApp, so it must stay reachable while the template is created.", "maxLength": 2048 } }, "required": [ "type" ] }, "TemplateButtonInput": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "quick_reply", "url", "catalog", "mpm", "flow" ], "description": "quick_reply sends a reply back when tapped (it arrives as a message with reply {id, title}). url opens a link. catalog opens the catalog of the number (no extra fields). mpm opens a selection of products you choose when you send (components.mpm). flow opens a WhatsApp Flow (flowId)." }, "text": { "type": "string", "example": "Confirm", "maxLength": 25 }, "payload": { "type": "string", "example": "appointment:123:confirm", "maxLength": 256, "description": "Only for quick_reply. It comes back as reply.id when the person taps the button. Without it, reply.id is the button text." }, "url": { "type": "string", "example": "https://clinic.example.com/appointments", "description": "Only for url, and then required. A public https link. It can end with one variable written like {{order_id}}, for example https://shop.example.com/orders/{{order_id}}: you give its value in variables when you send, and its sample in examples." }, "flowId": { "type": "string", "example": "1197715005513101", "description": "Only for flow, and then required: the id of a published Flow." }, "flowAction": { "type": "string", "enum": [ "navigate", "data_exchange" ], "description": "Only for flow. navigate opens the screen (the default)." }, "screen": { "type": "string", "example": "BOOKING", "description": "Only for flow with navigate: the id of the first screen." } }, "required": [ "type", "text" ] }, "TemplateCardHeader": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "exampleFileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files and purpose template_header, an image or a video that matches type. Send exampleFileId or exampleUrl, one of them." }, "exampleUrl": { "type": "string", "example": "https://files.example.com/chair.jpg", "description": "A public https sample WhatsApp reviews for the card.", "maxLength": 2048 } }, "required": [ "type" ] }, "TemplateCardButton": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "quick_reply", "url" ] }, "text": { "type": "string", "example": "Buy", "maxLength": 25 }, "payload": { "type": "string", "description": "Only for quick_reply." }, "url": { "type": "string", "description": "Only for url, and then required: https, no variables." } }, "required": [ "type", "text" ] }, "TemplateCard": { "type": "object", "properties": { "header": { "$ref": "#/components/schemas/TemplateCardHeader" }, "body": { "type": "string", "maxLength": 160, "description": "In every card or in none." }, "buttons": { "description": "One or two buttons. Every card has the same buttons in the same order.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateCardButton" } } }, "required": [ "header", "buttons" ] }, "TemplateCarousel": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "media", "product" ], "description": "media: 2 to 10 cards with an image or video, fixed when the template is created. product: cards that show products of the catalog; the template is created with two and you send 2 to 10 cards." }, "cards": { "description": "Only for media.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateCard" } }, "buttonText": { "type": "string", "example": "View", "maxLength": 25, "description": "Only for product, and then required: the text of the button of each card." } }, "required": [ "type" ] }, "CreateTemplate": { "type": "object", "properties": { "name": { "type": "string", "example": "we_miss_you", "description": "lowercase_with_underscores.", "pattern": "^[a-z][a-z0-9_]{0,511}$" }, "language": { "type": "string", "example": "es", "maxLength": 20, "minLength": 2 }, "category": { "type": "string", "enum": [ "marketing", "utility", "authentication" ] }, "body": { "type": "string", "example": "Hola {{name}}, usa el código {{coupon}}.", "description": "With named variables: {{name}}.", "maxLength": 1024, "minLength": 1 }, "footer": { "type": "string", "example": "Responde STOP para no recibir más.", "maxLength": 60 }, "header": { "$ref": "#/components/schemas/TemplateHeaderInput" }, "buttons": { "description": "Up to 10 buttons, at most 2 of type url. Marketing templates also get the opt-out button, which counts toward the 10: in the language of the template, or your own text if you send a quick_reply with payload lelemon_stop_messages. Quick replies are kept together before the links.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateButtonInput" } }, "carousel": { "description": "Swipeable cards under the body, with media or with catalog products. WhatsApp checks the combination with the other parts when it reviews the template.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "media", "product" ], "description": "media: 2 to 10 cards with an image or video, fixed when the template is created. product: cards that show products of the catalog; the template is created with two and you send 2 to 10 cards." }, "cards": { "description": "Only for media.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateCard" } }, "buttonText": { "type": "string", "example": "View", "maxLength": 25, "description": "Only for product, and then required: the text of the button of each card." } }, "required": [ "type" ] }, "examples": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "name": "Ana", "coupon": "VUELVE10" }, "description": "A sample value for each variable." }, "phoneNumberIds": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string" } } ], "example": "all" } }, "required": [ "name", "language", "category", "body", "examples", "phoneNumberIds" ] }, "TemplateHeader": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "image", "video" ] } }, "required": [ "type" ] }, "TemplateButton": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "quick_reply", "url", "catalog", "mpm", "flow" ] }, "text": { "type": "string" }, "payload": { "type": "string" }, "url": { "type": "string" }, "flowId": { "type": "string" }, "flowAction": { "type": "string", "enum": [ "navigate", "data_exchange" ] }, "screen": { "type": "string" } }, "required": [ "type", "text" ] }, "Template": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "template" ] }, "id": { "type": "string", "example": "tpl_02y0e5MANqacVbmtn1YyeJ" }, "name": { "type": "string" }, "language": { "type": "string" }, "category": { "type": "string", "enum": [ "marketing", "utility", "authentication" ] }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "paused" ] }, "rejectionReason": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "footer": { "type": [ "string", "null" ] }, "header": { "anyOf": [ { "$ref": "#/components/schemas/TemplateHeader" }, { "type": "null" } ] }, "buttons": { "description": "Texts of the buttons.", "type": "array", "items": { "type": "string" } }, "buttonActions": { "description": "The buttons with their type, payload or link.", "type": "array", "items": { "$ref": "#/components/schemas/TemplateButton" } }, "carousel": { "anyOf": [ { "$ref": "#/components/schemas/TemplateCarousel" }, { "type": "null" } ] }, "variables": { "description": "The variables of the body and of the links of the buttons.", "type": "array", "items": { "type": "string" } }, "examples": { "type": "object", "additionalProperties": { "type": "string" } }, "phoneNumberIds": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string" } } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "language", "category", "status", "rejectionReason", "body", "footer", "header", "buttons", "buttonActions", "carousel", "variables", "examples", "phoneNumberIds", "createdAt", "updatedAt" ] }, "TemplateSync": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "template_sync" ] }, "checked": { "type": "number", "description": "Templates checked against WhatsApp." }, "updated": { "type": "number", "description": "Templates whose status changed." }, "imported": { "type": "number", "description": "Templates found on WhatsApp that were not here." } }, "required": [ "object", "checked", "updated", "imported" ] }, "TemplateList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateTemplate": { "type": "object", "properties": { "phoneNumberIds": { "oneOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string" } } ] } } }, "RenderTemplate": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "name": "Ana", "coupon": "VUELVE10" } } }, "required": [ "variables" ] }, "TemplateRender": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "template_render" ] }, "text": { "type": "string" }, "buttons": { "type": "array", "items": { "type": "string" } } }, "required": [ "object", "text", "buttons" ] }, "HeaderDocument": { "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/estado-de-cuenta.pdf", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 }, "filename": { "type": "string", "example": "estado-de-cuenta.pdf", "maxLength": 255 } } }, "HeaderMedia": { "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "SendCatalog": { "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the message. Without it WhatsApp uses the first product of the catalog.", "maxLength": 200 } } }, "SendProductSection": { "type": "object", "properties": { "title": { "type": "string", "example": "Cakes", "maxLength": 24 }, "productIds": { "example": [ "sku-1", "sku-2" ], "type": "array", "items": { "type": "string" }, "maxItems": 30 } }, "required": [ "title", "productIds" ] }, "SendMpm": { "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "maxLength": 200 }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/SendProductSection" }, "maxItems": 10 } }, "required": [ "thumbnailProductId", "sections" ] }, "SendFlow": { "type": "object", "properties": { "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer.", "maxLength": 200 }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen of the Flow starts with." } } }, "CardMedia": { "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files, with purpose message_media in a single message or campaign_media in a campaign. Send fileId or url, one of them." }, "url": { "type": "string", "example": "https://files.example.com/chair.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "SendCard": { "type": "object", "properties": { "image": { "description": "The image of the card. Media carousels with image cards.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files, with purpose message_media in a single message or campaign_media in a campaign. Send fileId or url, one of them." }, "url": { "type": "string", "example": "https://files.example.com/chair.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "video": { "description": "The video of the card. Media carousels with video cards.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files, with purpose message_media in a single message or campaign_media in a campaign. Send fileId or url, one of them." }, "url": { "type": "string", "example": "https://files.example.com/chair.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "productId": { "type": "string", "example": "sku-1", "description": "The product of the card (retailer id in the catalog). Product carousels.", "maxLength": 200 } } }, "SendComponents": { "type": "object", "properties": { "headerImage": { "description": "The image of the header, for templates with an image header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "headerVideo": { "description": "The video of the header, for templates with a video header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "catalog": { "description": "For templates with a catalog button. Optional.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the message. Without it WhatsApp uses the first product of the catalog.", "maxLength": 200 } } }, "mpm": { "description": "For templates with a multi-product button. Required then.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "maxLength": 200 }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/SendProductSection" }, "maxItems": 10 } }, "required": [ "thumbnailProductId", "sections" ] }, "flow": { "description": "For templates with a flow button. Optional.", "type": "object", "properties": { "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer.", "maxLength": 200 }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen of the Flow starts with." } } }, "catalogId": { "type": "string", "example": "1234567890", "description": "The catalog of the products of a product carousel. It must be the one connected to the number that sends.", "maxLength": 100 }, "cards": { "description": "For templates with a carousel. Media carousel: as many cards as the template has, each with its image or video. Product carousel: 2 to 10 cards, each with a productId.", "type": "array", "items": { "$ref": "#/components/schemas/SendCard" }, "maxItems": 10 } } }, "TestTemplate": { "type": "object", "properties": { "to": { "type": "string", "example": "+56987654321", "maxLength": 50 }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "description": "By default, the sample values the template was created with." }, "document": { "$ref": "#/components/schemas/HeaderDocument" }, "components": { "description": "What the template needs besides its variables: image or video header, products, Flow data, cards.", "type": "object", "properties": { "headerImage": { "description": "The image of the header, for templates with an image header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "headerVideo": { "description": "The video of the header, for templates with a video header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "catalog": { "description": "For templates with a catalog button. Optional.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the message. Without it WhatsApp uses the first product of the catalog.", "maxLength": 200 } } }, "mpm": { "description": "For templates with a multi-product button. Required then.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "maxLength": 200 }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/SendProductSection" }, "maxItems": 10 } }, "required": [ "thumbnailProductId", "sections" ] }, "flow": { "description": "For templates with a flow button. Optional.", "type": "object", "properties": { "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer.", "maxLength": 200 }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen of the Flow starts with." } } }, "catalogId": { "type": "string", "example": "1234567890", "description": "The catalog of the products of a product carousel. It must be the one connected to the number that sends.", "maxLength": 100 }, "cards": { "description": "For templates with a carousel. Media carousel: as many cards as the template has, each with its image or video. Product carousel: 2 to 10 cards, each with a productId.", "type": "array", "items": { "$ref": "#/components/schemas/SendCard" }, "maxItems": 10 } } } }, "required": [ "to" ] }, "MessageFailure": { "type": "object", "properties": { "code": { "type": "string", "example": "131047" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "WhatsappMessage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_message" ] }, "id": { "type": "string", "example": "wam_3Dk0x8bVw1TqS9mYp3RkLd" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "sent", "delivered", "read", "failed", "skipped", "canceled" ] }, "templateId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "caseId": { "type": [ "string", "null" ] }, "sendAt": { "type": [ "string", "null" ], "format": "date-time" }, "skipReason": { "type": [ "string", "null" ], "description": "Why it was skipped: opted_out, no_phone, template_not_approved, human_in_control, cooldown, not_allowed or canceled." }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/MessageFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "templateId", "contactId", "caseId", "sendAt", "skipReason", "failure", "createdAt" ] }, "Recipient": { "oneOf": [ { "type": "object", "title": "contactId", "properties": { "contactId": { "type": "string", "example": "ctc_02y0e5MANqacVbmtn1YyeJ" } }, "required": [ "contactId" ], "additionalProperties": false }, { "type": "object", "title": "externalRef", "properties": { "externalRef": { "type": "string", "example": "cust-88123", "maxLength": 255 } }, "required": [ "externalRef" ], "additionalProperties": false }, { "type": "object", "title": "phone", "properties": { "phone": { "type": "string", "example": "+56987654321", "maxLength": 50 } }, "required": [ "phone" ], "additionalProperties": false } ] }, "OnReply": { "type": "object", "properties": { "agentId": { "type": "string", "example": "agt_K2m8Rw", "description": "The agent that continues if they answer." }, "stageId": { "type": "string", "example": "stg_Or4", "description": "The stage where the case continues if they answer." }, "instructions": { "type": "string", "example": "The customer got a 10% coupon. Help them place an order.", "description": "The context the agent gets if they answer. For this send, it replaces the fixed instructions of the trigger.", "maxLength": 4000 } } }, "CreateWhatsappMessage": { "type": "object", "properties": { "to": { "description": "Exactly one of contactId, externalRef or phone.", "oneOf": [ { "type": "object", "title": "contactId", "properties": { "contactId": { "type": "string", "example": "ctc_02y0e5MANqacVbmtn1YyeJ" } }, "required": [ "contactId" ], "additionalProperties": false }, { "type": "object", "title": "externalRef", "properties": { "externalRef": { "type": "string", "example": "cust-88123", "maxLength": 255 } }, "required": [ "externalRef" ], "additionalProperties": false }, { "type": "object", "title": "phone", "properties": { "phone": { "type": "string", "example": "+56987654321", "maxLength": 50 } }, "required": [ "phone" ], "additionalProperties": false } ] }, "templateId": { "type": "string", "example": "tpl_02y0e5MANqacVbmtn1YyeJ" }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "name": "Ana", "coupon": "VUELVE10" } }, "document": { "description": "The document of the header, for templates that have one.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/estado-de-cuenta.pdf", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 }, "filename": { "type": "string", "example": "estado-de-cuenta.pdf", "maxLength": 255 } } }, "components": { "description": "What the template needs besides its variables: image or video header, products, Flow data, cards.", "type": "object", "properties": { "headerImage": { "description": "The image of the header, for templates with an image header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "headerVideo": { "description": "The video of the header, for templates with a video header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "catalog": { "description": "For templates with a catalog button. Optional.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the message. Without it WhatsApp uses the first product of the catalog.", "maxLength": 200 } } }, "mpm": { "description": "For templates with a multi-product button. Required then.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "maxLength": 200 }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/SendProductSection" }, "maxItems": 10 } }, "required": [ "thumbnailProductId", "sections" ] }, "flow": { "description": "For templates with a flow button. Optional.", "type": "object", "properties": { "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer.", "maxLength": 200 }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen of the Flow starts with." } } }, "catalogId": { "type": "string", "example": "1234567890", "description": "The catalog of the products of a product carousel. It must be the one connected to the number that sends.", "maxLength": 100 }, "cards": { "description": "For templates with a carousel. Media carousel: as many cards as the template has, each with its image or video. Product carousel: 2 to 10 cards, each with a productId.", "type": "array", "items": { "$ref": "#/components/schemas/SendCard" }, "maxItems": 10 } } }, "sendAt": { "type": "string", "format": "date-time", "description": "Schedule it. Without it the message goes out now." }, "from": { "type": "string", "example": "pn_2Gx0x8bVw1TqS9mYp3RkLd", "description": "The number to send from. By default the one that fits the template and the agent." }, "onReply": { "$ref": "#/components/schemas/OnReply" } }, "required": [ "to", "templateId", "variables" ] }, "EventContact": { "type": "object", "properties": { "externalRef": { "type": "string", "example": "cust-88123", "description": "Your own id for this person. The contact is created if it is new.", "maxLength": 255, "minLength": 1 }, "name": { "type": "string", "example": "Ana Rojas", "maxLength": 255, "minLength": 1 }, "phone": { "type": "string", "example": "+56987654321", "maxLength": 50, "minLength": 1 }, "email": { "type": "string", "example": "ana@example.com", "maxLength": 255, "format": "email", "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\\.)+[A-Za-z]{2,}$" }, "companyId": { "type": "string", "example": "cpy_4Zq0x8bVw1TqS9mYp3RkLd", "description": "Links the contact to a company. When you omit it the company stays. A company that does not exist in the organization is a 400 with param contact.companyId." } }, "required": [ "externalRef" ] }, "CreateContactEvent": { "type": "object", "properties": { "type": { "type": "string", "example": "customer.inactive_30_days", "description": "Your own name for the fact.", "maxLength": 100, "minLength": 1 }, "contact": { "$ref": "#/components/schemas/EventContact" }, "data": { "type": "object", "additionalProperties": true, "example": { "firstName": "Ana", "coupon": "VUELVE10" }, "description": "Values the triggers can map to template variables." }, "onReply": { "description": "For this event only. onReply.instructions replaces the fixed instructions of the trigger.", "type": "object", "properties": { "agentId": { "type": "string", "example": "agt_K2m8Rw", "description": "The agent that continues if they answer." }, "stageId": { "type": "string", "example": "stg_Or4", "description": "The stage where the case continues if they answer." }, "instructions": { "type": "string", "example": "The customer got a 10% coupon. Help them place an order.", "description": "The context the agent gets if they answer. For this send, it replaces the fixed instructions of the trigger.", "maxLength": 4000 } } } }, "required": [ "type", "contact" ] }, "TriggerEmail": { "type": "object", "properties": { "subject": { "type": "string", "example": "We miss you, {{name}}", "description": "Subject. {{variable}} placeholders are filled from variables.", "pattern": "^[^\\r\\n]*$", "maxLength": 998, "minLength": 1 }, "text": { "type": "string", "example": "Hi {{name}}, here is a coupon: {{coupon}}.", "description": "Text of the first email, with {{variable}} placeholders.", "maxLength": 50000, "minLength": 1 }, "from": { "type": "string", "example": "support@mail.acme.com", "description": "The sender. It must belong to a verified domain. Defaults to the first verified domain.", "maxLength": 320 } }, "required": [ "subject", "text" ] }, "TriggerOnReplyInput": { "type": "object", "properties": { "agentId": { "type": "string", "example": "agt_K2m8Rw" }, "stageId": { "type": "string", "example": "stg_Or4" } } }, "TriggerOpenCase": { "type": "object", "properties": { "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "stageId": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "pipelineId", "stageId" ] }, "TriggerMoveCase": { "type": "object", "properties": { "stageId": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "stageId" ] }, "TriggerOnEventInput": { "type": "object", "properties": { "openCase": { "description": "Opens a case for the contact in this pipeline and stage when the event arrives. If the contact already has an open case in the pipeline, it is left where it is.", "type": "object", "properties": { "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "stageId": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "pipelineId", "stageId" ] }, "moveCase": { "description": "Moves the open case of the contact in the pipeline of this stage to the stage when the event arrives. If the contact has no open case there, nothing happens.", "type": "object", "properties": { "stageId": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "stageId" ] } } }, "DailyWindow": { "type": "object", "properties": { "from": { "type": "string", "example": "10:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "to": { "type": "string", "example": "21:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "timezone": { "type": "string", "example": "America/Santiago", "default": "America/Santiago", "maxLength": 60 } }, "required": [ "from", "to" ] }, "TriggerCadenceInput": { "type": "object", "properties": { "attempts": { "type": "integer", "example": 3, "minimum": 1, "maximum": 5, "description": "How many times the template is sent at most, the first one included. The first goes out when the event arrives." }, "intervalHours": { "type": "integer", "example": 24, "minimum": 1, "maximum": 336, "description": "Hours between one attempt and the next." }, "window": { "description": "Attempts only go out between from and to in this time zone. An attempt that falls outside waits for the next from.", "type": "object", "properties": { "from": { "type": "string", "example": "10:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "to": { "type": "string", "example": "21:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "timezone": { "type": "string", "example": "America/Santiago", "default": "America/Santiago", "maxLength": 60 } }, "required": [ "from", "to" ] }, "stopOn": { "type": "array", "default": [ "reply", "opt_out", "stage_changed", "closed" ], "description": "What ends the cadence, checked right before each attempt: reply (the contact wrote back), opt_out, stage_changed (the case left the stage it was in) and closed (the case was closed). opt_out always applies, even if you leave it out.", "items": { "type": "string", "enum": [ "reply", "opt_out", "stage_changed", "closed" ] }, "uniqueItems": true } }, "required": [ "attempts", "intervalHours" ] }, "CreateTrigger": { "type": "object", "properties": { "contactEvent": { "type": "string", "example": "customer.inactive_30_days", "description": "Your own name for the fact, as you send it in POST /v2/contact-events.", "maxLength": 100, "minLength": 1 }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ], "default": "whatsapp", "description": "whatsapp sends the template. email sends the text in email and opens a case the agent continues." }, "templateId": { "type": "string", "example": "tpl_02y0e5MANqacVbmtn1YyeJ", "description": "The template to send. A whatsapp trigger needs either templateId or onEvent. Without templateId it sends no message and only acts on the case, so variables, onReply, instructions, cooldownDays and cadence do not apply." }, "email": { "description": "Required for email.", "type": "object", "properties": { "subject": { "type": "string", "example": "We miss you, {{name}}", "description": "Subject. {{variable}} placeholders are filled from variables.", "pattern": "^[^\\r\\n]*$", "maxLength": 998, "minLength": 1 }, "text": { "type": "string", "example": "Hi {{name}}, here is a coupon: {{coupon}}.", "description": "Text of the first email, with {{variable}} placeholders.", "maxLength": 50000, "minLength": 1 }, "from": { "type": "string", "example": "support@mail.acme.com", "description": "The sender. It must belong to a verified domain. Defaults to the first verified domain.", "maxLength": 320 } }, "required": [ "subject", "text" ] }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "name": "data.firstName", "coupon": "data.coupon" }, "description": "Template (or email placeholder) variable to a path in the event: data.x or contact.name, contact.phone, contact.email, contact.externalRef. Any other text is used as is. Required when the trigger has a template or an email; leave it out when it has neither." }, "onReply": { "$ref": "#/components/schemas/TriggerOnReplyInput" }, "instructions": { "type": "string", "example": "The customer got a 10% coupon. Help them place an order.", "description": "Context the agent gets if they answer. An event can replace it with onReply.instructions.", "maxLength": 4000 }, "cooldownDays": { "type": "integer", "example": 30, "description": "Don't send twice to the same contact within this many days.", "maximum": 3650, "minimum": 1 }, "onEvent": { "description": "What happens to the contact case the moment the event arrives, without waiting for a reply. Send exactly one of openCase or moveCase. WhatsApp triggers only. With no templateId it is the whole trigger: the case is opened or moved and no message goes out.", "type": "object", "properties": { "openCase": { "description": "Opens a case for the contact in this pipeline and stage when the event arrives. If the contact already has an open case in the pipeline, it is left where it is.", "type": "object", "properties": { "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "stageId": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "pipelineId", "stageId" ] }, "moveCase": { "description": "Moves the open case of the contact in the pipeline of this stage to the stage when the event arrives. If the contact has no open case there, nothing happens.", "type": "object", "properties": { "stageId": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "stageId" ] } } }, "cadence": { "description": "Repeat the template up to attempts times, every intervalHours, until the contact replies, opts out, or the case changes stage or closes. WhatsApp triggers only. cooldownDays applies to the first attempt only.", "type": "object", "properties": { "attempts": { "type": "integer", "example": 3, "minimum": 1, "maximum": 5, "description": "How many times the template is sent at most, the first one included. The first goes out when the event arrives." }, "intervalHours": { "type": "integer", "example": 24, "minimum": 1, "maximum": 336, "description": "Hours between one attempt and the next." }, "window": { "description": "Attempts only go out between from and to in this time zone. An attempt that falls outside waits for the next from.", "type": "object", "properties": { "from": { "type": "string", "example": "10:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "to": { "type": "string", "example": "21:00", "pattern": "^([01]\\d|2[0-3]):([0-5]\\d)$" }, "timezone": { "type": "string", "example": "America/Santiago", "default": "America/Santiago", "maxLength": 60 } }, "required": [ "from", "to" ] }, "stopOn": { "type": "array", "default": [ "reply", "opt_out", "stage_changed", "closed" ], "description": "What ends the cadence, checked right before each attempt: reply (the contact wrote back), opt_out, stage_changed (the case left the stage it was in) and closed (the case was closed). opt_out always applies, even if you leave it out.", "items": { "type": "string", "enum": [ "reply", "opt_out", "stage_changed", "closed" ] }, "uniqueItems": true } }, "required": [ "attempts", "intervalHours" ] } }, "required": [ "contactEvent" ] }, "TriggerOnReply": { "type": "object", "properties": { "agentId": { "type": [ "string", "null" ] }, "stageId": { "type": [ "string", "null" ] } }, "required": [ "agentId", "stageId" ] }, "TriggerOnEvent": { "type": "object", "properties": { "openCase": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOpenCase" }, { "type": "null" } ] }, "moveCase": { "anyOf": [ { "$ref": "#/components/schemas/TriggerMoveCase" }, { "type": "null" } ] } }, "required": [ "openCase", "moveCase" ] }, "TriggerCadence": { "type": "object", "properties": { "attempts": { "type": "integer" }, "intervalHours": { "type": "integer" }, "window": { "anyOf": [ { "$ref": "#/components/schemas/DailyWindow" }, { "type": "null" } ] }, "stopOn": { "type": "array", "items": { "type": "string", "enum": [ "reply", "opt_out", "stage_changed", "closed" ] } } }, "required": [ "attempts", "intervalHours", "window", "stopOn" ] }, "Trigger": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "trigger" ] }, "id": { "type": "string", "example": "trg_1Qa0x8bVw1TqS9mYp3RkLd" }, "contactEvent": { "type": "string" }, "channel": { "type": "string", "enum": [ "whatsapp", "email" ] }, "templateId": { "type": [ "string", "null" ] }, "email": { "anyOf": [ { "$ref": "#/components/schemas/TriggerEmail" }, { "type": "null" } ] }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "onReply": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnReply" }, { "type": "null" } ] }, "instructions": { "type": [ "string", "null" ] }, "cooldownDays": { "type": [ "integer", "null" ] }, "onEvent": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnEvent" }, { "type": "null" } ] }, "cadence": { "anyOf": [ { "$ref": "#/components/schemas/TriggerCadence" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "paused" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "contactEvent", "channel", "templateId", "email", "variables", "onReply", "instructions", "cooldownDays", "onEvent", "cadence", "status", "createdAt", "updatedAt" ] }, "TriggerList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Trigger" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CadenceRun": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "cadence_run" ] }, "id": { "type": "string", "example": "cdr_4Zq0x8bVw1TqS9mYp3RkLd" }, "contact": { "type": "object", "description": "The contact the cadence is running for.", "example": { "id": "ctc_4Zq0x8bVw1TqS9mYp3RkLd", "name": "Ana Pérez" } }, "status": { "type": "string", "enum": [ "active", "completed", "stopped" ] }, "stopReason": { "type": [ "string", "null" ], "example": "reply", "description": "Why the cadence stopped. Null while it is active." }, "attemptsMade": { "type": "number", "example": 1 }, "maxAttempts": { "type": "number", "example": 3 }, "intervalHours": { "type": "number", "example": 24 }, "nextAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the next attempt goes out. Null unless it is active." }, "startedAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "contact", "status", "stopReason", "attemptsMade", "maxAttempts", "intervalHours", "nextAt", "startedAt", "updatedAt" ] }, "CadenceRunList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CadenceRun" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateTrigger": { "type": "object", "properties": { "contactEvent": { "type": "string", "maxLength": 100, "minLength": 1 }, "templateId": { "type": "string" }, "email": { "description": "Email triggers only.", "type": "object", "properties": { "subject": { "type": "string", "example": "We miss you, {{name}}", "description": "Subject. {{variable}} placeholders are filled from variables.", "pattern": "^[^\\r\\n]*$", "maxLength": 998, "minLength": 1 }, "text": { "type": "string", "example": "Hi {{name}}, here is a coupon: {{coupon}}.", "description": "Text of the first email, with {{variable}} placeholders.", "maxLength": 50000, "minLength": 1 }, "from": { "type": "string", "example": "support@mail.acme.com", "description": "The sender. It must belong to a verified domain. Defaults to the first verified domain.", "maxLength": 320 } }, "required": [ "subject", "text" ] }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "onReply": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnReplyInput" }, { "type": "null" } ] }, "instructions": { "type": [ "string", "null" ], "maxLength": 4000 }, "cooldownDays": { "type": [ "integer", "null" ], "maximum": 3650, "minimum": 1 }, "onEvent": { "anyOf": [ { "$ref": "#/components/schemas/TriggerOnEventInput" }, { "type": "null" } ] }, "cadence": { "anyOf": [ { "$ref": "#/components/schemas/TriggerCadenceInput" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "OptOut": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "opt_out" ] }, "contactId": { "type": "string", "example": "ctc_4Fq2ZdQ0x8bVw1TqS9mYp3" }, "channel": { "type": "string", "enum": [ "whatsapp", "email", "voice" ] }, "source": { "type": "string", "enum": [ "contact", "organization" ], "description": "contact: they asked for it. organization: you set it through the API." }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "contactId", "channel", "source", "createdAt" ] }, "OptOutList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OptOut" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "ContactFilter": { "type": "object", "properties": { "tags": { "example": [ "vip" ], "type": "array", "items": { "type": "string" }, "maxItems": 20 }, "lastCaseAfter": { "type": "string", "format": "date", "example": "2026-01-01", "description": "Contacts with a case opened after this date." }, "createdAfter": { "type": "string", "format": "date", "description": "Contacts created after this date." } } }, "Audience": { "type": "object", "properties": { "contactFilter": { "$ref": "#/components/schemas/ContactFilter" }, "externalRefs": { "description": "Up to 10000 externalRefs.", "type": "array", "items": { "type": "string" }, "maxItems": 10000 } } }, "Schedule": { "type": "object", "properties": { "at": { "type": "string", "example": "2026-11-27T10:00:00-03:00", "description": "When the campaign starts after you launch it: a date-time, or \"now\" to start as soon as you launch it. \"now\" is saved as the moment you created the campaign, so reading it back gives a date-time. A date in the past also starts at once." }, "window": { "$ref": "#/components/schemas/DailyWindow" }, "batchSize": { "type": "integer", "example": 300, "default": 100, "maximum": 1000, "minimum": 1 }, "batchEveryMinutes": { "type": "integer", "example": 15, "default": 15, "maximum": 1440, "minimum": 1 } }, "required": [ "at" ] }, "CreateCampaign": { "type": "object", "properties": { "name": { "type": "string", "example": "Black Friday", "maxLength": 255, "minLength": 1 }, "templateId": { "type": "string", "example": "tpl_02y0e5MANqacVbmtn1YyeJ" }, "audience": { "description": "contactFilter or externalRefs.", "type": "object", "properties": { "contactFilter": { "$ref": "#/components/schemas/ContactFilter" }, "externalRefs": { "description": "Up to 10000 externalRefs.", "type": "array", "items": { "type": "string" }, "maxItems": 10000 } } }, "variables": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "name": "contact.name", "coupon": "BF26" }, "description": "Template variable to contact.name, contact.phone, contact.email or contact.externalRef. Any other text is used as is." }, "document": { "$ref": "#/components/schemas/HeaderDocument" }, "components": { "description": "What the template needs besides its variables: image or video header, products, Flow data, cards.", "type": "object", "properties": { "headerImage": { "description": "The image of the header, for templates with an image header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "headerVideo": { "description": "The video of the header, for templates with a video header.", "type": "object", "properties": { "fileId": { "type": "string", "example": "fil_4Zq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded with POST /v2/files. In a single message it needs purpose message_media; in a campaign, campaign_media. Preferred over a URL: WhatsApp gets the bytes from Lelemon, not from your server." }, "attachmentId": { "type": "string", "example": "att_1Bq0x8bVw1TqS9mYp3RkLd", "description": "A file you uploaded to a case. Use fileId for a file uploaded with POST /v2/files." }, "url": { "type": "string", "example": "https://files.example.com/promo.jpg", "description": "A public https URL that WhatsApp can download.", "maxLength": 2048 } } }, "catalog": { "description": "For templates with a catalog button. Optional.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the message. Without it WhatsApp uses the first product of the catalog.", "maxLength": 200 } } }, "mpm": { "description": "For templates with a multi-product button. Required then.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "maxLength": 200 }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/SendProductSection" }, "maxItems": 10 } }, "required": [ "thumbnailProductId", "sections" ] }, "flow": { "description": "For templates with a flow button. Optional.", "type": "object", "properties": { "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer.", "maxLength": 200 }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen of the Flow starts with." } } }, "catalogId": { "type": "string", "example": "1234567890", "description": "The catalog of the products of a product carousel. It must be the one connected to the number that sends.", "maxLength": 100 }, "cards": { "description": "For templates with a carousel. Media carousel: as many cards as the template has, each with its image or video. Product carousel: 2 to 10 cards, each with a productId.", "type": "array", "items": { "$ref": "#/components/schemas/SendCard" }, "maxItems": 10 } } }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "onReply": { "$ref": "#/components/schemas/OnReply" } }, "required": [ "name", "templateId", "audience", "schedule" ] }, "CampaignOnReply": { "type": "object", "properties": { "agentId": { "type": [ "string", "null" ] }, "stageId": { "type": [ "string", "null" ] }, "instructions": { "type": [ "string", "null" ] } }, "required": [ "agentId", "stageId", "instructions" ] }, "CampaignCounts": { "type": "object", "properties": { "recipients": { "type": "number" }, "pending": { "type": "number" }, "queued": { "type": "number" }, "sent": { "type": "number" }, "delivered": { "type": "number" }, "read": { "type": "number" }, "replied": { "type": "number", "description": "Recipients whose contact wrote back after receiving the message, counted once each. It is not a status: a recipient can be read and replied at once." }, "failed": { "type": "number" }, "skipped": { "type": "number" } }, "required": [ "recipients", "pending", "queued", "sent", "delivered", "read", "replied", "failed", "skipped" ] }, "Campaign": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "example": "cmp_BF26" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] }, "templateId": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "components": { "description": "The components saved on the campaign (media headers by fileId or url, cards, products), as you sent them. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/SendComponents" }, { "type": "null" } ] }, "document": { "description": "The document header saved on the campaign, as you sent it. null when it has none.", "anyOf": [ { "$ref": "#/components/schemas/HeaderDocument" }, { "type": "null" } ] }, "onReply": { "description": "Who continues the conversation if the contact answers, as you sent it. null when it was not set.", "anyOf": [ { "$ref": "#/components/schemas/CampaignOnReply" }, { "type": "null" } ] }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "pauseReason": { "type": [ "string", "null" ], "description": "Why it paused by itself, if it did." }, "counts": { "$ref": "#/components/schemas/CampaignCounts" }, "launchedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "status", "templateId", "audience", "variables", "components", "document", "onReply", "schedule", "pauseReason", "counts", "launchedAt", "createdAt", "updatedAt" ] }, "CampaignList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateCampaign": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "minLength": 1 }, "templateId": { "type": "string" }, "audience": { "$ref": "#/components/schemas/Audience" }, "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "document": { "description": "Send null to remove the saved document header.", "anyOf": [ { "$ref": "#/components/schemas/HeaderDocument" }, { "type": "null" } ] }, "components": { "description": "What the template needs besides its variables: image or video header, products, Flow data, cards. Send null to remove the saved components.", "anyOf": [ { "$ref": "#/components/schemas/SendComponents" }, { "type": "null" } ] }, "schedule": { "$ref": "#/components/schemas/Schedule" }, "onReply": { "description": "Send null to remove who continues if they answer.", "anyOf": [ { "$ref": "#/components/schemas/OnReply" }, { "type": "null" } ] } } }, "CampaignCost": { "type": "object", "properties": { "amount": { "type": "number", "example": 4.445 }, "currency": { "type": "string", "example": "USD" }, "effectiveFrom": { "type": "string", "format": "date", "example": "2026-10-01", "description": "Date from which the Meta rate card used for the estimate applies." } }, "required": [ "amount", "currency", "effectiveFrom" ] }, "CampaignPreview": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign_preview" ] }, "recipients": { "type": "number", "description": "Contacts that would get the message." }, "skipped": { "type": "object", "additionalProperties": { "type": "integer" }, "example": { "opted_out": 41, "no_phone": 12, "not_allowed": 3 } }, "sample": { "type": [ "string", "null" ] }, "estimatedCost": { "description": "List price of the messages that would be sent: the rate of the template category in the market of each phone number, from the WhatsApp Business Platform rate card published by Meta (https://developers.facebook.com/docs/whatsapp/pricing). It is the list rate before the volume tiers of utility and authentication messages, so the real charge can be lower; it is zero when nobody would receive the message.", "type": "object", "properties": { "amount": { "type": "number", "example": 4.445 }, "currency": { "type": "string", "example": "USD" }, "effectiveFrom": { "type": "string", "format": "date", "example": "2026-10-01", "description": "Date from which the Meta rate card used for the estimate applies." } }, "required": [ "amount", "currency", "effectiveFrom" ] } }, "required": [ "object", "recipients", "skipped", "sample", "estimatedCost" ] }, "CampaignRecipient": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign_recipient" ] }, "contactId": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "queued", "sent", "delivered", "read", "failed", "skipped" ] }, "skipReason": { "type": [ "string", "null" ] }, "whatsappMessageId": { "type": [ "string", "null" ] } }, "required": [ "object", "contactId", "status", "skipReason", "whatsappMessageId" ] }, "CampaignRecipientList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignRecipient" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "CreateEmailDomain": { "type": "object", "properties": { "name": { "type": "string", "example": "mail.acme.com", "description": "The domain emails go out from.", "maxLength": 253, "minLength": 3 }, "defaultFromLocal": { "type": "string", "example": "hello", "default": "hello", "description": "The part before the @ of the default sender address." }, "inboundAgentId": { "type": "string", "example": "agt_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The agent that opens a case when a stranger writes to an address of this domain. Without it, mail from people with no thread is ignored." } }, "required": [ "name" ] }, "DnsRecord": { "type": "object", "properties": { "record": { "type": "string", "example": "DKIM", "description": "DKIM signs your emails; MX routes the replies to Lelemon." }, "type": { "type": "string", "example": "CNAME", "enum": [ "CNAME", "MX", "TXT" ] }, "name": { "type": "string", "example": "k3x9q2tz7p._domainkey.mail.acme.com" }, "value": { "type": "string" }, "priority": { "type": [ "integer", "null" ] }, "status": { "type": "string", "example": "verified" } }, "required": [ "record", "type", "name", "value", "priority", "status" ] }, "EmailDomain": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "email_domain" ] }, "id": { "type": "string", "example": "dom_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "mail.acme.com" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed" ], "description": "Only a verified domain can send. Add the records; verification completes on its own once DNS answers, and POST /v2/email/domains/{id}/verify checks it right away." }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } }, "defaultFrom": { "type": "string", "example": "hello@mail.acme.com" }, "inboundAgentId": { "type": [ "string", "null" ] }, "verifiedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "name", "status", "records", "defaultFrom", "inboundAgentId", "verifiedAt", "createdAt", "updatedAt" ] }, "EmailDomainList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailDomain" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "UpdateEmailDomain": { "type": "object", "properties": { "defaultFromLocal": { "type": "string", "example": "support" }, "inboundAgentId": { "type": [ "string", "null" ] } } }, "EmailRecipient": { "oneOf": [ { "type": "object", "title": "contactId", "properties": { "contactId": { "type": "string", "example": "ctc_02y0e5MANqacVbmtn1YyeJ" } }, "required": [ "contactId" ], "additionalProperties": false }, { "type": "object", "title": "externalRef", "properties": { "externalRef": { "type": "string", "example": "cust-88123", "maxLength": 255 } }, "required": [ "externalRef" ], "additionalProperties": false }, { "type": "object", "title": "email", "properties": { "email": { "type": "string", "example": "ana@example.com", "maxLength": 320 } }, "required": [ "email" ], "additionalProperties": false } ] }, "CreateEmailMessage": { "type": "object", "properties": { "to": { "description": "Exactly one of contactId, externalRef or email.", "oneOf": [ { "type": "object", "title": "contactId", "properties": { "contactId": { "type": "string", "example": "ctc_02y0e5MANqacVbmtn1YyeJ" } }, "required": [ "contactId" ], "additionalProperties": false }, { "type": "object", "title": "externalRef", "properties": { "externalRef": { "type": "string", "example": "cust-88123", "maxLength": 255 } }, "required": [ "externalRef" ], "additionalProperties": false }, { "type": "object", "title": "email", "properties": { "email": { "type": "string", "example": "ana@example.com", "maxLength": 320 } }, "required": [ "email" ], "additionalProperties": false } ] }, "subject": { "type": "string", "example": "Your order is ready", "pattern": "^[^\\r\\n]*$", "maxLength": 998, "minLength": 1 }, "text": { "type": "string", "example": "Hi Ana, your order is ready to pick up.", "maxLength": 50000, "minLength": 1 }, "from": { "type": "string", "example": "support@mail.acme.com", "description": "The sender. It must belong to a verified domain. Defaults to the first verified domain.", "maxLength": 320 }, "onReply": { "description": "Who continues if they answer. The agent needs the email channel. Without agentId or stageId the case reuses the open email case of the contact.", "type": "object", "properties": { "agentId": { "type": "string", "example": "agt_K2m8Rw", "description": "The agent that continues if they answer." }, "stageId": { "type": "string", "example": "stg_Or4", "description": "The stage where the case continues if they answer." }, "instructions": { "type": "string", "example": "The customer got a 10% coupon. Help them place an order.", "description": "The context the agent gets if they answer. For this send, it replaces the fixed instructions of the trigger.", "maxLength": 4000 } } } }, "required": [ "to", "subject", "text" ] }, "EmailMessage": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "email_message" ] }, "id": { "type": "string", "example": "eml_3Dk0x8bVw1TqS9mYp3RkLd" }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ] }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "bounced", "failed", "skipped", "received", "rejected" ] }, "caseId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "subject": { "type": [ "string", "null" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "skipReason": { "type": [ "string", "null" ], "description": "Why it was skipped: opted_out, recipient_not_allowed, no_email, human_in_control, cooldown, no_verified_domain or open_case_elsewhere." }, "failure": { "anyOf": [ { "$ref": "#/components/schemas/MessageFailure" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "direction", "status", "caseId", "contactId", "subject", "from", "to", "skipReason", "failure", "createdAt" ] }, "TeamPipeline": { "type": "object", "properties": { "id": { "type": "string", "example": "ppl_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Ventas" } }, "required": [ "id", "name" ] }, "TeamMember": { "type": "object", "properties": { "id": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The same id that GET /v2/members lists." }, "name": { "type": [ "string", "null" ], "example": "Ana Pérez" }, "email": { "type": [ "string", "null" ], "example": "ana@empresa.cl" }, "role": { "type": "string" }, "isLeader": { "type": "boolean", "description": "Whether the member leads the team." }, "receivesCases": { "type": "boolean", "description": "Whether the assignment gives this member new cases." } }, "required": [ "id", "name", "email", "role", "isLeader", "receivesCases" ] }, "Team": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "example": "tem_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Soporte" }, "maxChatsPerPerson": { "type": [ "integer", "null" ], "description": "How many open chats a member can hold at once. null means no limit." }, "pipelines": { "type": "array", "items": { "$ref": "#/components/schemas/TeamPipeline" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } } }, "required": [ "object", "id", "name", "maxChatsPerPerson", "pipelines", "members" ] }, "TeamList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "TeamDetailMember": { "type": "object", "properties": { "id": { "type": "string", "example": "mbr_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The same id that GET /v2/members lists." }, "name": { "type": [ "string", "null" ], "example": "Ana Pérez" }, "email": { "type": [ "string", "null" ], "example": "ana@empresa.cl" }, "role": { "type": "string" }, "isLeader": { "type": "boolean", "description": "Whether the member leads the team." }, "receivesCases": { "type": "boolean", "description": "Whether the assignment gives this member new cases." }, "available": { "type": "boolean", "description": "Whether the member is marked available." }, "activeChats": { "type": "integer", "description": "Chats the member holds now." } }, "required": [ "id", "name", "email", "role", "isLeader", "receivesCases", "available", "activeChats" ] }, "TeamQueue": { "type": "object", "properties": { "count": { "type": "integer" }, "oldestSince": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when the oldest waiting case has been in the queue." } }, "required": [ "count", "oldestSince" ] }, "TeamDetail": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team" ] }, "id": { "type": "string", "example": "tem_4Zq0x8bVw1TqS9mYp3RkLd" }, "name": { "type": "string", "example": "Soporte" }, "maxChatsPerPerson": { "type": [ "integer", "null" ], "description": "How many open chats a member can hold at once. null means no limit." }, "pipelines": { "type": "array", "items": { "$ref": "#/components/schemas/TeamPipeline" } }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamDetailMember" } }, "queue": { "description": "Cases of the team pipelines waiting for someone to take them.", "type": "object", "properties": { "count": { "type": "integer" }, "oldestSince": { "type": [ "string", "null" ], "format": "date-time", "description": "Since when the oldest waiting case has been in the queue." } }, "required": [ "count", "oldestSince" ] } }, "required": [ "object", "id", "name", "maxChatsPerPerson", "pipelines", "members", "queue" ] }, "CreateTeam": { "type": "object", "properties": { "name": { "type": "string", "example": "Soporte", "maxLength": 120, "minLength": 1 }, "pipelineIds": { "example": [ "ppl_4Zq0x8bVw1TqS9mYp3RkLd" ], "maxItems": 200, "description": "Pipelines to move into the new team. A pipeline belongs to exactly one team, so it leaves the one it had.", "type": "array", "items": { "type": "string" } } }, "required": [ "name" ] }, "UpdateTeam": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120, "minLength": 1 }, "maxChatsPerPerson": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500, "description": "Open chats a member can hold at once. null removes the limit." } } }, "MergeTeam": { "type": "object", "properties": { "sourceTeamId": { "type": "string", "example": "tem_4Zq0x8bVw1TqS9mYp3RkLd", "description": "The team that goes into this one. Its pipelines and members move over and it is deleted." } }, "required": [ "sourceTeamId" ] }, "SetTeamMember": { "type": "object", "properties": { "isLeader": { "type": "boolean", "description": "Makes the member a leader, or stops them being one. A viewer cannot lead." }, "receivesCases": { "type": "boolean", "description": "Whether the assignment gives this member new cases." } } }, "LinearWebhook": { "type": "object", "properties": { "url": { "type": "string", "example": "https://api.lelemon.cl/webhooks/linear/lni_5RvP2aKq9XwLmN3tYbZc01", "description": "Paste it as the URL of a webhook in Linear (Settings, API, Webhooks) with the Issues resource and the team of this integration." }, "secretConfigured": { "type": "boolean", "description": "false until you save the signing secret Linear shows for that webhook. Without it every notification is rejected." } }, "required": [ "url", "secretConfigured" ] }, "LinearIntegration": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "linear_integration" ] }, "id": { "type": "string", "example": "lni_5RvP2aKq9XwLmN3tYbZc01" }, "teamId": { "type": "string", "example": "team-uuid" }, "teamKey": { "type": "string", "example": "LEL" }, "teamName": { "type": "string", "example": "Lelemon" }, "projectId": { "type": [ "string", "null" ] }, "webhook": { "$ref": "#/components/schemas/LinearWebhook" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "teamId", "teamKey", "teamName", "projectId", "webhook", "createdAt", "updatedAt" ] }, "ConnectLinear": { "type": "object", "properties": { "apiKey": { "type": "string", "example": "lin_api_xxxxxxxx", "description": "A Linear personal API key. Create it in Linear, Settings, Account, Security and access. Use the key of a service user that can see the team. It is stored encrypted and never returned.", "pattern": "^\\S+$", "maxLength": 255, "minLength": 8 }, "team": { "type": "string", "example": "LEL", "description": "The key or the id of the Linear team that receives the issues.", "pattern": "^\\S+$", "maxLength": 64, "minLength": 1 }, "project": { "type": [ "string", "null" ], "description": "The id of a project of that team. Without it the issues have no project.", "pattern": "^\\S+$", "maxLength": 64 } }, "required": [ "apiKey", "team" ] }, "UpdateLinear": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Replaces the API key.", "pattern": "^\\S+$", "maxLength": 255, "minLength": 8 }, "team": { "type": "string", "description": "Another team key or id.", "pattern": "^\\S+$", "maxLength": 64, "minLength": 1 }, "project": { "type": [ "string", "null" ], "description": "Another project id. null removes it.", "pattern": "^\\S+$", "maxLength": 64 }, "webhookSecret": { "type": "string", "description": "The signing secret Linear shows when you create the webhook. It is stored encrypted and never returned.", "pattern": "^\\S+$", "maxLength": 255, "minLength": 8 } } }, "EscalateToTeam": { "type": "object", "properties": { "answerStageId": { "type": "string", "example": "stg_02y0e5MANqacVbmtn1YyeJ", "description": "The stage of the same pipeline where the case goes when the team completes the issue. Without it, the stage of the pipeline with config.attentionRole answer; if the pipeline has none, the case stays where it is and only gets the answer as a note." } } }, "TeamEscalationIssue": { "type": "object", "properties": { "identifier": { "type": "string", "example": "LEL-123" }, "url": { "type": "string", "example": "https://linear.app/lelemon/issue/LEL-123" } }, "required": [ "identifier", "url" ] }, "TeamEscalation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team_escalation" ] }, "id": { "type": "string", "example": "esc_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": "string", "example": "cse_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "created", "completed", "failed", "canceled" ], "description": "pending: the issue is not created yet and Lelemon keeps trying. created: the team has it. completed: the team completed it and the answer reached the case. canceled: the team canceled the issue, so there is no answer and the case stays where it was. failed: Lelemon gave up; saving the Linear connection again tries again." }, "origin": { "type": "string", "enum": [ "stage", "manual" ], "description": "stage: the case entered a stage marked to escalate. manual: someone asked for it." }, "issue": { "anyOf": [ { "$ref": "#/components/schemas/TeamEscalationIssue" }, { "type": "null" } ] }, "answerStageId": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ], "description": "The last comment of the team on the issue, once it is completed." }, "lastError": { "type": [ "string", "null" ], "description": "Why the last attempt to create the issue failed." }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "status", "origin", "issue", "answerStageId", "answer", "lastError", "completedAt", "createdAt" ] }, "TeamEscalationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ] }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamEscalation" } } }, "required": [ "object", "hasMore", "nextCursor", "data" ] }, "DryRun": { "type": "object", "description": "What a dryRun answer adds to the normal one: nothing was saved, sent or charged, and an id in it is not saved.", "properties": { "dryRun": { "type": "boolean", "const": true, "description": "Present and true when the request had dryRun=true." } } }, "CreateContactMessage": { "type": "object", "properties": { "author": { "type": "string", "const": "contact" }, "text": { "type": "string", "example": "Hola, te devolvemos el envío.", "maxLength": 4096, "minLength": 1 }, "actor": { "description": "Who is speaking, for an embedded copilot. Only with author contact. It travels signed to every action and MCP server of this turn as the actor, marked as declared by your key and not verified by Lelemon. It is kept for this turn only.", "type": "object", "properties": { "id": { "type": "string", "example": "user_8841", "description": "The id of the person in your system. Lelemon does not verify it: it is stored as declared by your key.", "pattern": "^[^\\r\\n]*$", "maxLength": 128, "minLength": 1 }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ], "description": "The role of the person in your system, from lowest to highest. A key of a subaccount cannot declare a role above staff." }, "name": { "type": "string", "example": "Ana Pérez", "pattern": "^[^\\r\\n]*$", "maxLength": 200, "minLength": 1 } }, "required": [ "id", "role" ] } }, "required": [ "author", "text" ], "additionalProperties": false, "example": { "author": "contact", "text": "Where is my order?", "actor": { "id": "user_8841", "role": "staff" } } }, "CreateTeamTextMessage": { "type": "object", "properties": { "author": { "type": "string", "const": "team" }, "text": { "type": "string", "example": "Hola, te devolvemos el envío.", "maxLength": 4096, "minLength": 1 }, "authorName": { "type": "string", "example": "Camila", "description": "Who signs a team message. Defaults to the author name of the key.", "maxLength": 255, "minLength": 1 }, "visibility": { "type": "string", "enum": [ "public", "internal" ], "default": "public", "description": "internal is a note only your team sees: it never reaches the person or the agent, and it needs neither cases:send nor control of the case." }, "subject": { "type": "string", "example": "Your order", "description": "Email cases only. The subject of the thread. Required on the first message of the case and ignored after that.", "pattern": "^[^\\r\\n]*$", "maxLength": 998, "minLength": 1 }, "attachmentIds": { "example": [ "att_4Zq0x8bVw1TqS9mYp3RkLd" ], "description": "Files already uploaded with POST /v2/cases/{id}/attachments, sent by the channel of the case. Each file goes as its own message, and the text is the caption of the first. The response is the first message. Team messages only.", "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, "required": [ "author", "text" ], "additionalProperties": false, "example": { "author": "team", "text": "Your order leaves today.", "authorName": "Ana Pérez", "visibility": "public" } }, "CreateTeamInteractiveMessage": { "type": "object", "properties": { "author": { "type": "string", "const": "team" }, "interactive": { "description": "A WhatsApp message with buttons, a list, a product, a product list or the catalog, instead of text. Team messages on WhatsApp cases only, inside the 24 hours window (422 interactive_unsupported_channel on other channels, 422 channel_window_closed after the window). Do not send text or attachmentIds with it: interactive.body is the text. The tap of the person arrives as a message with reply {id, title}.", "oneOf": [ { "$ref": "#/components/schemas/InteractiveButtonsMessage" }, { "$ref": "#/components/schemas/InteractiveListMessage" }, { "$ref": "#/components/schemas/InteractiveProductMessage" }, { "$ref": "#/components/schemas/InteractiveProductListMessage" }, { "$ref": "#/components/schemas/InteractiveCatalogMessage" }, { "$ref": "#/components/schemas/InteractiveCtaUrlMessage" }, { "$ref": "#/components/schemas/InteractiveFlowMessage" }, { "$ref": "#/components/schemas/InteractiveLocationRequestMessage" }, { "$ref": "#/components/schemas/InteractiveContactRequestMessage" }, { "$ref": "#/components/schemas/InteractiveCallMessage" }, { "$ref": "#/components/schemas/InteractiveCarouselMessage" } ], "discriminator": { "propertyName": "type", "mapping": { "buttons": "#/components/schemas/InteractiveButtonsMessage", "list": "#/components/schemas/InteractiveListMessage", "product": "#/components/schemas/InteractiveProductMessage", "product_list": "#/components/schemas/InteractiveProductListMessage", "catalog": "#/components/schemas/InteractiveCatalogMessage", "cta_url": "#/components/schemas/InteractiveCtaUrlMessage", "flow": "#/components/schemas/InteractiveFlowMessage", "location_request": "#/components/schemas/InteractiveLocationRequestMessage", "contact_request": "#/components/schemas/InteractiveContactRequestMessage", "call": "#/components/schemas/InteractiveCallMessage", "carousel": "#/components/schemas/InteractiveCarouselMessage" } } }, "authorName": { "type": "string", "example": "Camila", "description": "Who signs a team message. Defaults to the author name of the key.", "maxLength": 255, "minLength": 1 } }, "required": [ "author", "interactive" ], "additionalProperties": false, "example": { "author": "team", "interactive": { "type": "buttons", "body": "Do you want to confirm the order?", "buttons": [ { "id": "yes", "title": "Yes" }, { "id": "no", "title": "No" } ] }, "authorName": "Ana Pérez" } }, "CreateTeamFilesMessage": { "type": "object", "properties": { "author": { "type": "string", "const": "team" }, "text": { "type": "string", "example": "Hola, te devolvemos el envío.", "maxLength": 4096, "minLength": 1 }, "authorName": { "type": "string", "example": "Camila", "description": "Who signs a team message. Defaults to the author name of the key.", "maxLength": 255, "minLength": 1 }, "subject": { "type": "string", "example": "Your order", "description": "Email cases only. The subject of the thread. Required on the first message of the case and ignored after that.", "pattern": "^[^\\r\\n]*$", "maxLength": 998, "minLength": 1 }, "attachmentIds": { "example": [ "att_4Zq0x8bVw1TqS9mYp3RkLd" ], "description": "Files already uploaded with POST /v2/cases/{id}/attachments, sent by the channel of the case. Each file goes as its own message, and the text is the caption of the first. The response is the first message. Team messages only.", "type": "array", "items": { "type": "string" }, "maxItems": 10 } }, "required": [ "author", "attachmentIds" ], "additionalProperties": false, "example": { "author": "team", "attachmentIds": [ "att_02y0e5MANqacVbmtn1YyeJ" ] } }, "InteractiveButtonsMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "buttons" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "headerMedia": { "description": "An image, video or document above the body. Only for buttons and cta_url. Do not send it together with header.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document" ] }, "url": { "type": "string", "example": "https://cdn.example.com/order.jpg", "description": "A public https link WhatsApp can download." } }, "required": [ "type", "url" ] }, "buttons": { "description": "Only for type buttons: 1 to 3 buttons.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveButton" } } }, "required": [ "type", "body", "buttons" ], "additionalProperties": false }, "InteractiveListMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "list": { "description": "Only for type list.", "type": "object", "properties": { "button": { "type": "string", "example": "See days", "maxLength": 24, "description": "The label of the button that opens the list." }, "sections": { "description": "Up to 10 sections and 10 rows in total.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveSection" } } }, "required": [ "button", "sections" ] } }, "required": [ "type", "body", "list" ], "additionalProperties": false }, "InteractiveProductMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "product" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "product": { "description": "Only for type product.", "type": "object", "properties": { "catalogId": { "type": "string", "example": "1234567890", "description": "The id of the catalog connected to the WhatsApp number." }, "productId": { "type": "string", "example": "sku-1", "description": "The product id in the catalog (content_id / retailer id), not a Lelemon id." } }, "required": [ "catalogId", "productId" ] } }, "required": [ "type", "product" ], "additionalProperties": false }, "InteractiveProductListMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "product_list" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "products": { "description": "Only for type product_list.", "type": "object", "properties": { "catalogId": { "type": "string", "example": "1234567890" }, "sections": { "description": "Up to 10 sections and 30 products in total.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveProductSection" } } }, "required": [ "catalogId", "sections" ] } }, "required": [ "type", "body", "header", "products" ], "additionalProperties": false }, "InteractiveCatalogMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "catalog" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "catalog": { "description": "Only for type catalog.", "type": "object", "properties": { "thumbnailProductId": { "type": "string", "example": "sku-1", "description": "The product whose image heads the catalog message." } } } }, "required": [ "type" ], "additionalProperties": false }, "InteractiveCtaUrlMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "cta_url" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "headerMedia": { "description": "An image, video or document above the body. Only for buttons and cta_url. Do not send it together with header.", "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video", "document" ] }, "url": { "type": "string", "example": "https://cdn.example.com/order.jpg", "description": "A public https link WhatsApp can download." } }, "required": [ "type", "url" ] }, "cta": { "description": "Only for type cta_url.", "type": "object", "properties": { "displayText": { "type": "string", "example": "Pay now", "maxLength": 20, "description": "The label of the button that opens the link." }, "url": { "type": "string", "example": "https://shop.example.com/pay/ord_1", "description": "A public https link. It opens in the browser of the person." } }, "required": [ "displayText", "url" ] } }, "required": [ "type", "body", "cta" ], "additionalProperties": false }, "InteractiveFlowMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "flow" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "header": { "type": "string", "maxLength": 60, "description": "Text above the body. Required for product_list." }, "footer": { "type": "string", "maxLength": 60 }, "flow": { "description": "Only for type flow.", "type": "object", "properties": { "flowId": { "type": "string", "example": "1197715005513101", "description": "The id of a published WhatsApp Flow of the account." }, "cta": { "type": "string", "example": "Book now", "maxLength": 20, "description": "The label of the button that opens the Flow." }, "action": { "type": "string", "enum": [ "navigate", "data_exchange" ], "description": "navigate opens the screen you name in screen (the default). data_exchange asks your Flow endpoint for the first screen." }, "screen": { "type": "string", "example": "BOOKING", "description": "The id of the first screen. Required when you send data." }, "data": { "type": "object", "additionalProperties": true, "description": "The values the first screen starts with." }, "token": { "type": "string", "example": "case-42", "description": "Your own correlation id. WhatsApp returns it with the Flow answer. Without it, the platform uses the flowId." } }, "required": [ "flowId", "cta" ] } }, "required": [ "type", "body", "flow" ], "additionalProperties": false }, "InteractiveLocationRequestMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "location_request" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." } }, "required": [ "type", "body" ], "additionalProperties": false }, "InteractiveContactRequestMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "contact_request" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." } }, "required": [ "type", "body" ], "additionalProperties": false }, "InteractiveCallMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "call" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "call": { "description": "Only for type call. Optional: WhatsApp has defaults.", "type": "object", "properties": { "displayText": { "type": "string", "example": "Call support", "maxLength": 20, "description": "The label of the call button. WhatsApp uses \"Call Now\"." }, "ttlMinutes": { "type": "integer", "example": 1440, "minimum": 1, "maximum": 43200, "description": "Minutes the button stays active. WhatsApp uses 10080 (7 days)." }, "payload": { "type": "string", "example": "order-4471", "maxLength": 512, "description": "Comes back with the call, to know which message it came from." } } } }, "required": [ "type", "body" ], "additionalProperties": false }, "InteractiveCarouselMessage": { "type": "object", "properties": { "type": { "type": "string", "const": "carousel" }, "body": { "type": "string", "maxLength": 1024, "description": "The text of the message. Required for buttons, list and product_list." }, "carousel": { "description": "Only for type carousel.", "type": "object", "properties": { "cards": { "description": "Between 2 and 10 cards, in the order the person swipes them.", "type": "array", "items": { "$ref": "#/components/schemas/InteractiveCard" } } }, "required": [ "cards" ] } }, "required": [ "type", "body", "carousel" ], "additionalProperties": false }, "ApprovalCondition": { "description": "A comparison {param, op, value}, or a group {all: [...]} or {any: [...]} of conditions. Up to 3 levels and 10 comparisons.", "oneOf": [ { "$ref": "#/components/schemas/ApprovalComparison" }, { "$ref": "#/components/schemas/ApprovalAllOf" }, { "$ref": "#/components/schemas/ApprovalAnyOf" } ] }, "ApprovalComparison": { "type": "object", "properties": { "param": { "type": "string", "example": "amount", "description": "A path into the arguments of the action, like amount or order.total." }, "op": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "exists" ] }, "value": { "description": "What to compare with. A list for in; leave it out for exists." } }, "required": [ "param", "op" ], "additionalProperties": false }, "ApprovalAllOf": { "type": "object", "properties": { "all": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ApprovalCondition" }, "description": "Every condition must hold." } }, "required": [ "all" ], "additionalProperties": false }, "ApprovalAnyOf": { "type": "object", "properties": { "any": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ApprovalCondition" }, "description": "At least one condition must hold." } }, "required": [ "any" ], "additionalProperties": false }, "ConnectorManifest": { "type": "object", "required": [ "format", "name", "views" ], "properties": { "format": { "const": "lelemon-connector/v1" }, "name": { "type": "string", "minLength": 1, "maxLength": 2000 }, "lookup": { "type": "object", "properties": { "byId": { "type": "boolean" }, "byEmail": { "type": "boolean" } } }, "views": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "id", "name", "description" ], "properties": { "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 2000 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "inputSchema": { "type": "object", "properties": { "type": { "const": "object" }, "properties": { "type": "object", "maxProperties": 10, "additionalProperties": { "type": "object", "required": [ "type" ], "properties": { "type": { "enum": [ "string", "integer", "number", "boolean" ] }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 }, "enum": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 2000 } } } } }, "required": { "type": "array", "items": { "type": "string" } } } } } } } } }, "ConnectorAccountSearch": { "type": "object", "required": [ "object", "data", "hasMore", "nextCursor" ], "properties": { "object": { "const": "list" }, "data": { "type": "array", "maxItems": 50, "items": { "type": "object", "required": [ "id", "title" ], "properties": { "id": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 2000 }, "subtitle": { "type": "string", "minLength": 1, "maxLength": 2000 } } } }, "hasMore": { "type": "boolean" }, "nextCursor": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^[A-Za-z0-9_=.-]{1,500}$" } ] } } }, "ConnectorAccount": { "type": "object", "required": [ "object", "id", "title", "sections" ], "properties": { "object": { "const": "account" }, "id": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 2000 }, "subtitle": { "type": "string", "minLength": 1, "maxLength": 2000 }, "sections": { "type": "array", "maxItems": 20, "items": { "type": "object", "required": [ "title", "components" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 2000 }, "components": { "type": "array", "maxItems": 50, "items": { "oneOf": [ { "type": "object", "required": [ "type", "key", "label", "valueType", "value" ], "properties": { "type": { "const": "field" }, "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 2000 }, "valueType": { "enum": [ "text", "number", "money", "date", "status", "link" ] }, "value": { "type": [ "string", "number", "boolean", "null" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "sensitive": { "type": "boolean" }, "specialCategory": { "type": "boolean" } } }, { "type": "object", "required": [ "type", "columns", "rows" ], "properties": { "type": { "const": "table" }, "title": { "type": "string", "minLength": 1, "maxLength": 2000 }, "columns": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "required": [ "key", "label", "valueType" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 2000 }, "valueType": { "enum": [ "text", "number", "money", "date", "status", "link" ] }, "sensitive": { "type": "boolean" }, "specialCategory": { "type": "boolean" } } } }, "rows": { "type": "array", "maxItems": 200, "items": { "type": "object", "required": [ "id", "cells" ], "properties": { "id": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" }, "accountId": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" }, "cells": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } } } } } } }, { "type": "object", "required": [ "type", "label" ], "properties": { "type": { "const": "badge" }, "label": { "type": "string", "minLength": 1, "maxLength": 2000 }, "tone": { "enum": [ "neutral", "info", "success", "warning", "danger" ] } } }, { "type": "object", "required": [ "type", "id", "label", "url" ], "properties": { "type": { "const": "action" }, "id": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 2000 }, "url": { "type": "string", "pattern": "^https://", "description": "https only, host inside the sites of the connector" } } } ] } } } } } } }, "ConnectorView": { "type": "object", "required": [ "object", "columns", "data", "hasMore", "nextCursor" ], "properties": { "object": { "const": "list" }, "columns": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "required": [ "key", "label", "valueType" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 2000 }, "valueType": { "enum": [ "text", "number", "money", "date", "status", "link" ] }, "sensitive": { "type": "boolean" }, "specialCategory": { "type": "boolean" } } } }, "data": { "type": "array", "maxItems": 200, "items": { "type": "object", "required": [ "id", "cells" ], "properties": { "id": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" }, "accountId": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" }, "cells": { "type": "object", "additionalProperties": { "type": [ "string", "number", "boolean", "null" ] } } } } }, "hasMore": { "type": "boolean" }, "nextCursor": { "oneOf": [ { "type": "null" }, { "type": "string", "pattern": "^[A-Za-z0-9_=.-]{1,500}$" } ] } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Makes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "IdempotencyKeyRequired": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Required on this operation: without it the answer is 400. Makes the request safe to retry. Once it starts running, its final response (2xx, 4xx or 5xx) is kept for 24 hours and the same key gets it back, without repeating the effect. A request rejected before it runs leaves the key free. A replayed create omits the secret. The same key with a different request is rejected with 409 idempotency_key_reused.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, "LelemonSubaccount": { "name": "Lelemon-Subaccount", "in": "header", "required": false, "description": "The subaccount (sub_…) this request acts on. Only for the keys of a platform account; without it the request acts on the account itself.", "schema": { "type": "string", "pattern": "^sub_[0-9A-Za-z]{22}$" } } } }, "x-error-codes": [ { "code": "invalid_request", "status": 400, "title": "Invalid request", "cause": "A field of the request is missing, has the wrong type or breaks a limit, or the body has a field that does not exist. The `param` of the answer names the first field that failed and the `detail` says which rule it broke.", "fix": { "summary": "Correct the field named in `param` as the detail says, then send the request again.", "action": "set" } }, { "code": "unknown_field", "status": 400, "title": "Unknown field", "cause": "The body has a field the route does not document. `param` names the first one, and the detail lists up to ten. Remove it and send the request again. Free-form maps such as `metadata` accept any key.", "fix": { "summary": "Remove the field named in `param` from the body, or check its spelling against the API reference, then send the request again.", "action": "remove" } }, { "code": "invalid_cursor", "status": 400, "title": "Invalid cursor", "cause": "The `cursor` is not one this API issued, was changed on the way, or was issued for a list with other filters. A cursor is only valid for the same filters and the same list.", "fix": { "summary": "Drop the cursor and list again from the first page. A cursor only works with the filters it was issued for.", "action": "remove", "param": "cursor" } }, { "code": "api_key_invalid", "status": 401, "title": "Invalid API key", "detail": "Missing, invalid or revoked API key. Send it as Authorization: Bearer .", "fix": { "summary": "Send an API key in the Authorization header as `Bearer `.", "action": "set", "param": "Authorization" } }, { "code": "unauthorized", "status": 401, "title": "Unauthorized", "detail": "Missing, invalid or revoked API key. Send it as Authorization: Bearer .", "fix": { "summary": "Send an API key in the Authorization header as `Bearer `.", "action": "set", "param": "Authorization" } }, { "code": "scope_missing", "status": 403, "title": "Scope missing", "cause": "The key is valid but was created without the scope this operation needs. The operation page in the API reference lists the scope it requires and `missingScopes` in the answer names the ones this key lacks.", "fix": { "summary": "Read the scopes of this key. An administrator creates a key with the missing scope.", "action": "call", "endpoint": "GET /v2/me" } }, { "code": "agent_not_exposed", "status": 403, "title": "Agent not exposed", "detail": "This agent is internal and was not created through the API, so it is not exposed. Create a copilot with POST /v2/agents and audience internal.", "fix": { "summary": "Use an agent that the API exposes. List the agents first.", "action": "call", "endpoint": "GET /v2/agents" } }, { "code": "forbidden", "status": 403, "title": "Forbidden", "cause": "The key is valid and has the scope, but what it asks for is not allowed to it: the object belongs to another organization or subaccount, or the role behind the key is too low.", "porOmision": "This key cannot do this.", "fix": { "summary": "The key is valid but not allowed this action. Use a key of the organization that owns the object, with a role that can do it. Do not retry unchanged.", "action": "stop" } }, { "code": "grant_not_allowed", "status": 403, "title": "Grant not allowed", "cause": "A key can only hand out scopes it has itself, and some scopes (the `subaccounts:*` ones) are never handed down. The request asked for a scope the creating key cannot grant.", "fix": { "summary": "Ask for fewer scopes: only scopes the creating key has, and never a `subaccounts:*` scope.", "action": "set", "param": "scopes" } }, { "code": "organization_deleted", "status": 403, "title": "Organization deleted", "detail": "The organization of this key was deleted.", "fix": { "summary": "This organization no longer exists. Do not retry.", "action": "stop" } }, { "code": "subscription_canceled", "status": 403, "title": "Subscription canceled", "detail": "The subscription of this organization is canceled. The API is closed until it is reactivated.", "fix": { "summary": "The subscription must be reactivated by a person. Do not retry until then.", "action": "stop" } }, { "code": "budget_exceeded", "status": 402, "title": "Budget exceeded", "cause": "A budget with the action `stop` reached its monthly limit, so the agent no longer answers on that scope. The `budget` object of the answer says which budget, its limit and what was spent.", "porOmision": "The monthly budget is spent, so the agent does not answer. Stop sending messages; do not retry before the month resets or the limit is raised.", "fix": { "summary": "Stop sending messages to this agent. Tell the person it is paused. Raise the limit of the budget with a PATCH on its id under /v2/budgets, or wait for the month to reset.", "action": "stop" } }, { "code": "not_found", "status": 404, "title": "Not found", "cause": "No object with this id exists in the organization of the key. The id may have a typo, belong to another organization or subaccount, or the object was deleted.", "fix": { "summary": "Check the id: it must exist in this organization and in the same mode (test or live) as the key. List the resource to find a valid one.", "action": "set" } }, { "code": "method_not_allowed", "status": 405, "title": "Method not allowed", "cause": "The path exists but not with this HTTP method, for example a `DELETE` on a route that only reads. The API reference lists the methods of each path.", "fix": { "summary": "Use a method that the path accepts. The API reference lists them for each path.", "action": "set" } }, { "code": "conflict", "status": 409, "title": "Conflict", "cause": "The request is valid but clashes with the current state of the object, for example changing something that another request changed first or that is in a state that does not allow it. The `detail` says the state.", "fix": { "summary": "Read the object again to see its current state, then repeat the change on top of it.", "action": "set" } }, { "code": "idempotency_key_reused", "status": 409, "title": "Idempotency key reused", "cause": "This `Idempotency-Key` was already used within the last 24 hours with a different method, path or body. A key identifies one request: the same key must always carry the same request. It also answers when the response stored for the key was erased because it held personal data of a person who was suppressed: send the request again with a new key.", "fix": { "summary": "Send a new Idempotency-Key for this request. Reuse a key only to retry the exact same request.", "action": "set", "param": "Idempotency-Key" } }, { "code": "idempotency_key_in_use", "status": 409, "title": "Idempotency key in use", "cause": "A request with this `Idempotency-Key` is still running, so this second copy cannot be answered yet. It happens when a client retries before the first call finished.", "fix": { "summary": "Wait a moment and send the same request with the same Idempotency-Key.", "action": "retry", "param": "Idempotency-Key" } }, { "code": "agent_version_conflict", "status": 409, "title": "Agent version conflict", "detail": "Someone saved the agent after you read it. Read it again and retry with its current version.", "fix": { "summary": "Read the agent again and repeat the update with its current version.", "action": "call", "endpoint": "GET /v2/agents/{id}" } }, { "code": "external_ref_conflict", "status": 409, "title": "External reference conflict", "cause": "Another contact in this organization already has this `externalRef`. An `externalRef` is unique per organization.", "porOmision": "Another resource already uses this external reference.", "fix": { "summary": "Use another `externalRef`, or update the contact that already has it by its externalRef.", "action": "set", "param": "externalRef" } }, { "code": "actor_role_above_key", "status": 403, "title": "Actor role above the key", "detail": "The actor declares a role higher than this key can declare. Declare a lower role or use a key with more reach." }, { "code": "approval_not_pending", "status": 409, "title": "Approval not pending", "detail": "Someone decided this approval first, or it expired. Read it to see its status. It cannot be decided twice.", "fix": { "summary": "Read the approval to see who decided it and its status.", "action": "call", "endpoint": "GET /v2/approvals/{id}" } }, { "code": "approval_decision_not_allowed", "status": 403, "title": "Approval decision not allowed", "detail": "This key is not named as an approver by the policy of the tool, it created the request itself, or it lacks the approvals:write scope.", "fix": { "summary": "Do not retry. Only a key named as approver by the tool policy, other than the one that created the request, can decide it.", "action": "stop" } }, { "code": "review_not_available", "status": 422, "title": "Review not available", "detail": "Only a decision marked automatedDecision takes a review request, and an approval only once someone decided it.", "fix": { "summary": "Do not retry. The policy of the action has to mark automatedDecision, and an approval has to be decided, before a review can be asked.", "action": "stop" } }, { "code": "team_question_not_open", "status": 409, "title": "Team question not open", "detail": "The team question was already answered or closed. It cannot be answered twice.", "fix": { "summary": "Read the team question to see its status and its answer.", "action": "call", "endpoint": "GET /v2/team-questions/{id}" } }, { "code": "slot_not_available", "status": 409, "title": "Slot not available", "detail": "That time is no longer free in the agenda, or it was never one of its slots. Nothing was booked.", "fix": { "summary": "Read the availability of the agenda again and pick another slot. Repeating the same start will not work.", "action": "call", "endpoint": "GET /v2/scheduling/availability" } }, { "code": "meeting_not_active", "status": 409, "title": "Meeting not active", "detail": "The meeting is canceled, completed or was marked as a no-show, so it cannot be canceled or moved.", "fix": { "summary": "Read the meeting to see its status. A closed meeting cannot change.", "action": "call", "endpoint": "GET /v2/scheduling/meetings/{id}" } }, { "code": "invalid_cron", "status": 422, "title": "Invalid cron expression", "detail": "The cron expression could not be read. Use five fields (minute hour day-of-month month day-of-week), for example 0 9 2 * * for the 2nd of each month at 09:00.", "fix": { "summary": "Send a cron with five fields in cron, for example 0 9 2 * * for the 2nd of each month at 09:00.", "action": "set", "param": "cron" } }, { "code": "invalid_timezone", "status": 422, "title": "Invalid timezone", "detail": "The timezone is not an IANA name. Use a name such as America/Santiago.", "fix": { "summary": "Send an IANA timezone name in timezone, for example America/Santiago.", "action": "set", "param": "timezone" } }, { "code": "schedule_limit_reached", "status": 409, "title": "Schedule limit reached", "detail": "The agent or the organization already has the maximum number of scheduled tasks. Delete or reuse one before creating another.", "fix": { "summary": "Delete a scheduled task you no longer use with a DELETE on its id under /v2/schedules, or edit an existing one, then create it again.", "action": "call", "endpoint": "GET /v2/schedules" } }, { "code": "run_finished", "status": 409, "title": "Run finished", "detail": "The run already ended (completed, stopped, failed or canceled), so there is nothing left to cancel.", "fix": { "summary": "Do not retry. Read the run to see how it ended; to do the job again, create a new run.", "action": "call", "endpoint": "GET /v2/runs/{id}" } }, { "code": "run_not_waiting", "status": 409, "title": "Run not waiting for an answer", "detail": "The run is not paused with a question, so it has nothing to receive an answer. Read the run: only status waiting_for_answer takes one.", "fix": { "summary": "Read the run: it takes an answer only while its status is waiting_for_answer, and the question is in question.", "action": "call", "endpoint": "GET /v2/runs/{id}" } }, { "code": "case_agent_in_control", "status": 409, "title": "Agent in control", "detail": "The agent is handling this case and would answer over your message. Take control first, or close the case.", "fix": { "summary": "Take control of the case, then send the message again.", "action": "call", "endpoint": "POST /v2/cases/{id}/take-control" } }, { "code": "case_message_limit_reached", "status": 409, "title": "Message limit reached", "detail": "The case reached its limit of messages. Open a new case to keep talking.", "fix": { "summary": "Open a new case to keep talking with this person.", "action": "call", "endpoint": "POST /v2/cases" } }, { "code": "resource_in_use", "status": 409, "title": "Resource in use", "cause": "Something still depends on this object, for example a contact with open cases or a pipeline with a case in it, so it cannot be deleted. The `detail` names what depends on it.", "porOmision": "Something still depends on this resource.", "fix": { "summary": "Remove or close what depends on the object (the detail names it), then delete it again.", "action": "set" } }, { "code": "action_origin_not_allowed", "status": 403, "title": "Action origin not allowed", "detail": "This key may not create actions that call that site. An administrator adds the site to the key.", "fix": { "summary": "Only an administrator can allow that site on the key. Use an allowed site or ask for the change.", "action": "stop" } }, { "code": "action_destination_blocked", "status": 400, "title": "Destination blocked", "detail": "That address cannot be used. It must be a public http or https URL that answers.", "fix": { "summary": "Use a public https URL that answers. Private, local and unreachable addresses are never allowed.", "action": "set", "param": "url" } }, { "code": "phone_number_in_use", "status": 409, "title": "Phone number in use", "detail": "This number is already connected." }, { "code": "payload_too_large", "status": 413, "title": "Payload too large", "cause": "The body is bigger than the limit of the route. JSON bodies take up to 1 MB; a file route has its own limit, which the `detail` states.", "fix": { "summary": "Send a smaller body. Split the content across several requests.", "action": "set", "param": "body" } }, { "code": "unprocessable", "status": 422, "title": "Unprocessable", "cause": "The request is well formed and the fields are valid, but a rule of the object does not allow it in its current state. The `detail` names the rule and `param` the field when there is one.", "fix": { "summary": "The request is well formed but cannot be done as it is. Change what the detail says, using `param` when it is present, then send the request again.", "action": "set" } }, { "code": "agent_not_ready", "status": 422, "title": "Agent not ready", "cause": "The agent cannot be turned on yet because it lacks something required: instructions or a model. The `detail` lists what is missing and `param` names the first field.", "porOmision": "The agent lacks instructions or a model.", "fix": { "summary": "Activate the agent. If it lacks instructions or a model, the answer lists what to set on the agent.", "action": "call", "endpoint": "POST /v2/agents/{id}/activate" } }, { "code": "agent_channel_disabled", "status": 422, "title": "Agent channel disabled", "detail": "The agent does not have this channel enabled." }, { "code": "case_channel_not_api", "status": 422, "title": "Case not from the API", "detail": "Only cases that came through the API can be written to as the contact. On other channels the contact writes by themselves." }, { "code": "channel_window_closed", "status": 422, "title": "Channel window closed", "detail": "More than 24 hours passed since the last message of the person and WhatsApp only accepts approved templates now. The message was not sent.", "fix": { "summary": "Send an approved WhatsApp template instead of free text. List the templates first.", "action": "call", "endpoint": "GET /v2/whatsapp/templates" } }, { "code": "no_outbound_channel", "status": 422, "title": "No outbound channel", "detail": "This case has no channel to write to the person. The message was not sent." }, { "code": "interactive_unsupported_channel", "status": 422, "title": "Interactive messages need WhatsApp", "detail": "Buttons, lists and catalog messages only exist on WhatsApp. This case is on another channel. The message was not sent.", "fix": { "summary": "Send plain text with the text field. Interactive messages only go to cases on WhatsApp.", "action": "set", "param": "text" } }, { "code": "catalog_not_connected", "status": 422, "title": "Catalog not connected", "detail": "The WhatsApp number that sends the message has no catalog, or the catalogId is not the one connected to it. The message was not sent.", "fix": { "summary": "Save the id of the catalog connected in Meta on the number that sends, then send again. Use the same id in the message.", "action": "call", "endpoint": "PATCH /v2/whatsapp/phone-numbers/{id}" } }, { "code": "message_variable_missing", "status": 422, "title": "Message variable missing", "detail": "The template needs a variable that has no value. The message was not created." }, { "code": "template_not_approved", "status": 422, "title": "Template not approved", "detail": "WhatsApp has not approved this template, so nothing can be sent with it yet.", "fix": { "summary": "Pick a template whose status is approved. List the templates to find one.", "action": "call", "endpoint": "GET /v2/whatsapp/templates" } }, { "code": "no_whatsapp_number", "status": 422, "title": "No WhatsApp number", "detail": "The organization has no active WhatsApp number that can send this template." }, { "code": "template_across_accounts", "status": 422, "title": "Numbers on different WhatsApp accounts", "detail": "A template belongs to one WhatsApp Business Account. Choose numbers that share it." }, { "code": "sender_domain_not_verified", "status": 422, "title": "Sender domain not verified", "detail": "The sender address must belong to a verified domain of the organization. Check GET /v2/email/domains.", "fix": { "summary": "Use a sender address on a verified domain, or verify the domain first.", "action": "call", "endpoint": "GET /v2/email/domains" } }, { "code": "field_not_sensitive", "status": 422, "title": "Field not sensitive", "detail": "Only a field the pipeline marks as sensitive can be revealed. Read any other field from the case." }, { "code": "contact_without_email", "status": 422, "title": "Contact without email", "detail": "The contact has no email address to write to." }, { "code": "subject_required", "status": 422, "title": "Subject required", "detail": "The first email of a case needs a subject." }, { "code": "recipient_not_allowed", "status": 422, "title": "Recipient not allowed", "detail": "This organization cannot send email to that address." }, { "code": "contact_opted_out", "status": 422, "title": "Contact opted out", "detail": "The contact opted out of this channel, so nothing is sent to them." }, { "code": "presence_not_configured", "status": 409, "title": "Presence not configured", "cause": "Presence is off for this organization: no presence setting is saved yet, so signals have nothing to update and presence filters have nothing to read.", "porOmision": "Presence is not active for this organization. Turn on the presenceEnabled setting and send signals to POST /v2/presence-signals.", "fix": { "summary": "Turn presence on for the organization, then send signals again.", "action": "call", "endpoint": "PUT /v2/presence/settings" } }, { "code": "action_variable_needs_authorization", "status": 400, "title": "Action variable needs authorization", "cause": "The action sends `contact.phone` or `contact.whatsapp_id` to your system, and those two leave Lelemon only with the authorization of the destination (article 15 bis of Law 21.719). The request has no `authorization` and the action has no current one for this destination.", "porOmision": "These variables need the authorization of the destination. Send authorization with the request.", "fix": { "summary": "Read the current text with `GET /v2/actions/authorization` and send `authorization` with `purpose`, `destinationCountry` and that `version` in the same request.", "action": "set", "param": "authorization" } }, { "code": "action_variable_in_query", "status": 400, "title": "Action variable in the query", "cause": "In a `GET` action everything goes in the URL, and the URL stays in the logs of your system and of whatever sits in front of it. `contact.phone`, `contact.whatsapp_id` and the variables that come from a field of the case do not go there.", "porOmision": "These variables cannot go in a GET action. Use POST, PUT, PATCH or DELETE.", "fix": { "summary": "Change `request.method` to POST, PUT, PATCH or DELETE, or remove the variable named in the detail.", "action": "set", "param": "request.method" } }, { "code": "domain_in_use", "status": 409, "title": "Domain in use", "detail": "Another organization already registered this domain." }, { "code": "model_not_supported", "status": 422, "title": "Model not supported", "cause": "The `llmConfig.model` is not a public model id of the list in `GET /v2/models`, or it is one that was withdrawn.", "porOmision": "The model is not in GET /v2/models.", "fix": { "summary": "Pick a model from the list of supported models.", "action": "call", "endpoint": "GET /v2/models" } }, { "code": "thinking_not_supported", "status": 422, "title": "Thinking cannot be turned off", "cause": "The model in `llmConfig.model` cannot turn thinking off, so `thinking: \"off\"` is rejected. `GET /v2/models` says which models accept it.", "porOmision": "This model cannot turn thinking off.", "fix": { "summary": "Send thinking adaptive, or remove thinking, for the model in this field.", "action": "set" } }, { "code": "template_variable_missing", "status": 422, "title": "Template variable missing", "detail": "The instructions ask for a variable that has no value." }, { "code": "mcp_server_unreachable", "status": 422, "title": "MCP server unreachable", "detail": "The MCP server did not answer a tools request. Check the URL and the credentials. Redirects are not followed.", "fix": { "summary": "Check the URL and credentials of the MCP server. The URL must answer a tools request without redirecting.", "action": "set", "param": "url" } }, { "code": "linear_rejected", "status": 422, "title": "Linear rejected the request", "detail": "Linear did not accept the API key, the team or the project. Check that the key is valid and can see the team.", "fix": { "summary": "Send a Linear API key that is valid and can see the team, and the key or id of an existing team of that workspace.", "action": "set", "param": "apiKey" } }, { "code": "required_fields_missing", "status": 422, "title": "Required fields missing", "cause": "The stage the case is moving to or entering requires fields that the case does not have yet. `param` names the first missing one.", "porOmision": "The case lacks fields the stage requires.", "fix": { "summary": "Set the fields named in `param` on the case, then repeat the request.", "action": "set" } }, { "code": "unsupported_file_type", "status": 422, "title": "Unsupported file type", "detail": "Allowed: PDF, DOCX, TXT and MD.", "fix": { "summary": "Upload a PDF, DOCX, TXT or MD file.", "action": "set", "param": "file" } }, { "code": "rate_limited", "status": 429, "title": "Too many requests", "cause": "This key sent more than 3000 requests in the last minute. The RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers of every answer say where the key stands, and Retry-After says how many seconds to wait.", "detail": "Too many requests for this key. Wait Retry-After seconds.", "fix": { "summary": "Wait the number of seconds in the Retry-After header, then send the same request.", "action": "retry", "param": "Retry-After" } }, { "code": "data_connector_unavailable", "status": 422, "title": "Data connector unavailable", "detail": "Your connector did not answer in time, answered with an error, or its address is not reachable. Nothing was stored.", "fix": { "summary": "Check that your connector serves its manifest within 8 seconds, then call the check endpoint.", "action": "call", "endpoint": "POST /v2/data-connectors/{id}/check" } }, { "code": "data_connector_invalid_response", "status": 422, "title": "Data connector response is not valid", "cause": "Your connector answered, but an account card, a search answer or a view page does not follow lelemon-connector/v1. The `detail` lists the failing paths with the rule each breaks, never the values. The check endpoint reads the manifest only, so it can pass while a card fails.", "porOmision": "Your connector answered, but the response does not follow lelemon-connector/v1.", "fix": { "summary": "Fix the paths the detail lists in what your connector serves. To test a card before serving it, send it to the validate endpoint.", "action": "call", "endpoint": "POST /v2/data-connectors/format/validate" } }, { "code": "data_connector_not_ready", "status": 409, "title": "Data connector not ready", "detail": "The connector is not active. Read its signing secret, serve the format and call POST /v2/data-connectors/{id}/check.", "fix": { "summary": "Run the check endpoint until the connector is active.", "action": "call", "endpoint": "POST /v2/data-connectors/{id}/check" } }, { "code": "data_connector_limit", "status": 422, "title": "Data connector limit reached", "detail": "An organization can have up to 10 data connectors. Delete one first.", "fix": { "summary": "Delete a data connector you no longer use, then create it again.", "action": "stop" } }, { "code": "webhook_endpoint_limit", "status": 422, "title": "Webhook endpoint limit reached", "cause": "An organization can have up to 16 webhook endpoints, enabled or disabled. Every event is delivered to each endpoint that listens to it, so the cap also bounds how many deliveries one event can make.", "porOmision": "An organization can have up to 16 webhook endpoints. Delete one first.", "fix": { "summary": "List your endpoints, delete one you no longer use or add the event types to one that already exists, then create the endpoint again.", "action": "call", "endpoint": "GET /v2/webhook-endpoints" } }, { "code": "internal_error", "status": 500, "title": "Internal error", "detail": "Something failed on our side after the request started. The same Idempotency-Key returns this same error, so check whether the operation happened before retrying with a new key.", "fix": { "summary": "Check whether the operation happened, then retry with backoff and a new Idempotency-Key: the same key returns this error again. If it keeps failing, report the requestId.", "action": "retry", "param": "Idempotency-Key" } }, { "code": "service_unavailable", "status": 503, "title": "Service unavailable", "detail": "Lelemon is temporarily unavailable. Retry with backoff.", "fix": { "summary": "Retry with backoff and the same Idempotency-Key. Nothing was lost.", "action": "retry", "param": "Idempotency-Key" } } ], "webhooks": { "case.escalated": { "post": { "operationId": "webhooks.case.escalated", "summary": "Event case.escalated", "description": "An agent handed a case over to a person. Carries the contact, the reason and the last 20 messages. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "case.escalated", "example": "case.escalated" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "channel": { "type": [ "string", "null" ] } }, "required": [ "id", "pipelineId", "channel" ] }, "contact": { "type": "object", "properties": { "id": { "type": "string", "example": "ctc_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "externalRef": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email", "externalRef" ] }, "escalation": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] } }, "required": [ "reason", "priority", "summary" ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "role", "content", "createdAt" ] } } }, "required": [ "case", "contact", "escalation", "history" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "case.closed": { "post": { "operationId": "webhooks.case.closed", "summary": "Event case.closed", "description": "A case was closed: by the inactivity sweep, by entering a closing stage, by the agent ending the conversation or by POST /v2/cases/{id}/close. It fires once per case that really changed, after the closing is saved. reason is the closing reason saved in the case (for example inactividad, inactividad_despedida, seguimiento_agotado or the reason of the stage) and is null when none was set. closedBy tells who closed it: system (sweeps and automatic flows), stage, agent, api or user (a person in the dashboard). Read or complete the case with GET and PATCH /v2/cases/{id}. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "case.closed", "example": "case.closed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "id", "pipelineId" ] }, "reason": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "closed" ] }, "closedBy": { "type": "string", "enum": [ "system", "stage", "agent", "api", "user" ] }, "closedAt": { "type": "string", "format": "date-time" } }, "required": [ "case", "reason", "status", "closedBy", "closedAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "case.stage_entered": { "post": { "operationId": "webhooks.case.stage_entered", "summary": "Event case.stage_entered", "description": "A case entered a stage of its pipeline. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "case.stage_entered", "example": "case.stage_entered" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "pipelineName": { "type": [ "string", "null" ] } }, "required": [ "id", "pipelineId", "pipelineName" ] }, "stage": { "type": "object", "properties": { "id": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": [ "string", "null" ] }, "slug": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug" ] }, "previousStage": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string", "example": "stg_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] } ] }, "recipient": { "type": "object", "properties": { "externalSource": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] } }, "required": [ "externalSource", "externalId" ] }, "enteredAt": { "type": "string", "format": "date-time" } }, "required": [ "case", "stage", "previousStage", "recipient", "enteredAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.created": { "post": { "operationId": "webhooks.message.created", "summary": "Event message.created", "description": "Any new message of a case: the contact, the agent, your team or an internal note. It includes the replies of the agent, so you do not need to poll. Files are not included: read them with GET /v2/cases/{id}/messages. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.created", "example": "message.created" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "object": { "type": "string", "enum": [ "message" ] }, "id": { "type": "string", "example": "msg_3PqA0x8bVw1TqS9mYp3RkL" }, "caseId": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "author": { "type": "string", "enum": [ "contact", "agent", "team" ] }, "authorName": { "type": [ "string", "null" ] }, "visibility": { "type": "string", "enum": [ "public", "internal" ] }, "text": { "type": "string" }, "contentType": { "type": "string" }, "hasAttachment": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "caseId", "pipelineId", "author", "authorName", "visibility", "text", "contentType", "hasAttachment", "createdAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "case.control_changed": { "post": { "operationId": "webhooks.case.control_changed", "summary": "Event case.control_changed", "description": "A person took over a case, or the agent got it back, or the agent escalated it (escalated true). Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "case.control_changed", "example": "case.control_changed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "stageId": { "type": [ "string", "null" ] } }, "required": [ "id", "pipelineId", "stageId" ] }, "control": { "type": "string", "enum": [ "agent", "human" ] }, "escalated": { "type": "boolean" }, "controlledBy": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "externalRef": { "type": [ "string", "null" ] } }, "required": [ "case", "control", "escalated", "controlledBy", "contactId", "externalRef" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.received": { "post": { "operationId": "webhooks.message.received", "summary": "Event message.received", "description": "A person wrote to the organization. Carries no text, only where to read it. A cart sent from the WhatsApp catalog arrives with type order and its products; a tap on a button or list row arrives with type reply and the id and title tapped. A shared location arrives with type location, the answer of a WhatsApp Flow with type flow_response and a phone shared in answer to a contact_request with type contact: those three carry no data, because they are the personal data of the person. Read the note of the cart, the location, the Flow fields or the phone with GET /v2/cases/{id}/messages. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.received", "example": "message.received" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" }, "stageId": { "type": [ "string", "null" ] } }, "required": [ "id", "pipelineId", "stageId" ] }, "message": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_3PqA0x8bVw1TqS9mYp3RkL" }, "channel": { "type": [ "string", "null" ] }, "contentType": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "description": "order when the person sent a cart from the catalog, reply when they tapped a button or a list row, location when they shared a location, flow_response when they finished a WhatsApp Flow, contact when they shared their phone, otherwise the content type." }, "createdAt": { "type": "string", "format": "date-time" }, "reply": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title" ] }, { "type": "null" } ] }, "order": { "anyOf": [ { "type": "object", "properties": { "catalogId": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] } }, "required": [ "productId", "quantity", "price", "currency" ] } } }, "required": [ "catalogId", "items" ] }, { "type": "null" } ] } }, "required": [ "id", "channel", "contentType", "type", "createdAt", "reply", "order" ] } }, "required": [ "case", "message" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.human_sent": { "post": { "operationId": "webhooks.message.human_sent", "summary": "Event message.human_sent", "description": "A person of the team, or an integration, wrote to the contact. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.human_sent", "example": "message.human_sent" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": [ "string", "null" ] }, "channel": { "type": [ "string", "null" ] } }, "required": [ "id", "pipelineId", "channel" ] }, "recipient": { "type": "object", "properties": { "externalSource": { "type": [ "string", "null" ] }, "externalId": { "type": [ "string", "null" ] } }, "required": [ "externalSource", "externalId" ] }, "message": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_3PqA0x8bVw1TqS9mYp3RkL" }, "sequenceNumber": { "type": [ "integer", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "senderName": { "type": [ "string", "null" ] }, "hasFile": { "type": "boolean" } }, "required": [ "id", "sequenceNumber", "createdAt", "senderName", "hasFile" ] } }, "required": [ "case", "recipient", "message" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.agent_sent": { "post": { "operationId": "webhooks.message.agent_sent", "summary": "Event message.agent_sent", "description": "An agent wrote first to the contact because a trigger fired. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.agent_sent", "example": "message.agent_sent" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "kind": { "type": "string", "enum": [ "agent" ] }, "openPanel": { "type": [ "boolean", "null" ] }, "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "id", "pipelineId" ] }, "recipient": { "type": "object", "properties": { "externalId": { "type": [ "string", "null" ] } }, "required": [ "externalId" ] }, "message": { "type": "object", "properties": { "id": { "type": "string", "example": "msg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "id" ] }, "trigger": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "event": { "type": [ "string", "null" ] } }, "required": [ "id", "event" ] } }, "required": [ "kind", "openPanel", "case", "recipient", "message", "trigger" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "case.agent_failed": { "post": { "operationId": "webhooks.case.agent_failed", "summary": "Event case.agent_failed", "description": "The agent could not answer a message you sent with author contact. The message stays in the case. code budget_exceeded means the monthly budget ran out: stop writing until it resets or you raise the limit. Otherwise write again or take control of the case. requestId is the Request-Id of your POST. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "case.agent_failed", "example": "case.agent_failed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "pipelineId": { "type": "string", "example": "ppl_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "id", "pipelineId" ] }, "messageId": { "type": "string", "example": "msg_3PqA0x8bVw1TqS9mYp3RkL" }, "code": { "type": "string", "enum": [ "agent_error", "budget_exceeded" ] }, "requestId": { "type": [ "string", "null" ] } }, "required": [ "case", "messageId", "code", "requestId" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "case.turn_completed": { "post": { "operationId": "webhooks.case.turn_completed", "summary": "Event case.turn_completed", "description": "The agent finished a turn in a case. One turn can write several messages, so use this to know it is done instead of polling. Read what happened with GET /v2/cases/{id}/turns. It fires for completed, incomplete and failed turns. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "case.turn_completed", "example": "case.turn_completed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "case": { "type": "object", "properties": { "id": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" } }, "required": [ "id" ] }, "turnId": { "type": "string", "example": "trn_7Hc2LmQ0x8bVw1TqS9mYp3" }, "agentId": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "completed", "incomplete", "failed" ] }, "model": { "type": [ "string", "null" ] }, "tokens": { "type": "object", "properties": { "input": { "type": "integer" }, "output": { "type": "integer" } }, "required": [ "input", "output" ] }, "toolCalls": { "type": "integer" } }, "required": [ "case", "turnId", "agentId", "status", "model", "tokens", "toolCalls" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "budget.threshold_reached": { "post": { "operationId": "webhooks.budget.threshold_reached", "summary": "Event budget.threshold_reached", "description": "The conversations used in a monthly budget reached its alert percent. It fires once per month and budget, and again after you raise the limit and reach the new threshold. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "budget.threshold_reached", "example": "budget.threshold_reached" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "budget": { "type": "object", "properties": { "id": { "type": "string", "example": "bgt_7Hc2LmQ0x8bVw1TqS9mYp3" }, "scope": { "type": "string", "enum": [ "organization", "subaccount", "agent", "contact" ] }, "subjectId": { "type": [ "string", "null" ] } }, "required": [ "id", "scope", "subjectId" ] }, "alertPercent": { "type": "integer" }, "monthlyLimitConversations": { "type": "integer" }, "usedConversations": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" } }, "required": [ "budget", "alertPercent", "monthlyLimitConversations", "usedConversations", "resetsAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "budget.exceeded": { "post": { "operationId": "webhooks.budget.exceeded", "summary": "Event budget.exceeded", "description": "A monthly budget with enforcement stop ran out and the agent stopped. It fires once per month and budget. Raise the limit with PATCH /v2/budgets/{id} to resume at once. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "budget.exceeded", "example": "budget.exceeded" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "budget": { "type": "object", "properties": { "id": { "type": "string", "example": "bgt_7Hc2LmQ0x8bVw1TqS9mYp3" }, "scope": { "type": "string", "enum": [ "organization", "subaccount", "agent", "contact" ] }, "subjectId": { "type": [ "string", "null" ] } }, "required": [ "id", "scope", "subjectId" ] }, "monthlyLimitConversations": { "type": "integer" }, "usedConversations": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" } }, "required": [ "budget", "monthlyLimitConversations", "usedConversations", "resetsAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "mcp_server.failed": { "post": { "operationId": "webhooks.mcp_server.failed", "summary": "Event mcp_server.failed", "description": "An MCP server rejected the credential of a tool call (expired or revoked token) and was marked as failed. Reconnect it before your customers notice. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "mcp_server.failed", "example": "mcp_server.failed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "mcpServer": { "type": "object", "properties": { "id": { "type": "string", "example": "mcp_7Hc2LmQ0x8bVw1TqS9mYp3" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "reason": { "type": "string", "enum": [ "unauthorized" ] } }, "required": [ "mcpServer", "reason" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.status_changed": { "post": { "operationId": "webhooks.message.status_changed", "summary": "Event message.status_changed", "description": "A WhatsApp template message moved to another status: sent, delivered, read, skipped or canceled. Failures arrive as message.failed. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.status_changed", "example": "message.status_changed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "message": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_message" ] }, "id": { "type": "string", "example": "wam_3PqA0x8bVw1TqS9mYp3RkL" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "sending", "sent", "delivered", "read", "failed", "skipped", "canceled" ] }, "templateId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "caseId": { "type": [ "string", "null" ] }, "sendAt": { "type": [ "string", "null" ], "format": "date-time" }, "skipReason": { "type": [ "string", "null" ] }, "failure": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "templateId", "contactId", "caseId", "sendAt", "skipReason", "failure", "createdAt" ] }, "previousStatus": { "type": "string", "enum": [ "queued", "scheduled", "sending", "sent", "delivered", "read", "failed", "skipped", "canceled" ] } }, "required": [ "message", "previousStatus" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.failed": { "post": { "operationId": "webhooks.message.failed", "summary": "Event message.failed", "description": "A WhatsApp template message could not be delivered. message.failure.code says why. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.failed", "example": "message.failed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "message": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_message" ] }, "id": { "type": "string", "example": "wam_3PqA0x8bVw1TqS9mYp3RkL" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "sending", "sent", "delivered", "read", "failed", "skipped", "canceled" ] }, "templateId": { "type": [ "string", "null" ] }, "contactId": { "type": [ "string", "null" ] }, "caseId": { "type": [ "string", "null" ] }, "sendAt": { "type": [ "string", "null" ], "format": "date-time" }, "skipReason": { "type": [ "string", "null" ] }, "failure": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "templateId", "contactId", "caseId", "sendAt", "skipReason", "failure", "createdAt" ] }, "previousStatus": { "type": "string", "enum": [ "queued", "scheduled", "sending", "sent", "delivered", "read", "failed", "skipped", "canceled" ] } }, "required": [ "message", "previousStatus" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "contact.opted_out": { "post": { "operationId": "webhooks.contact.opted_out", "summary": "Event contact.opted_out", "description": "A contact stopped receiving messages on a channel, by their own request or by yours. Nothing more is sent to them there. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "contact.opted_out", "example": "contact.opted_out" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "contactId": { "type": "string", "example": "ctc_3PqA0x8bVw1TqS9mYp3RkL" }, "channel": { "type": "string", "enum": [ "whatsapp", "email", "voice" ] }, "source": { "type": "string", "enum": [ "contact", "organization" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "contactId", "channel", "source", "createdAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "contact.suppressed": { "post": { "operationId": "webhooks.contact.suppressed", "summary": "Event contact.suppressed", "description": "The erasure of a contact finished: its cases, messages, files and logs lost their content in our systems. Carries ids only. Erase the same person from every system where you copied them. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "contact.suppressed", "example": "contact.suppressed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "contactId": { "type": "string", "example": "ctc_3PqA0x8bVw1TqS9mYp3RkL" }, "suppressionId": { "type": "string", "example": "sup_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "contactId", "suppressionId" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "message.redacted": { "post": { "operationId": "webhooks.message.redacted", "summary": "Event message.redacted", "description": "A message was redacted: its text, file and copies were erased. Carries ids only. Redact the same message in every system where you copied it. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "message.redacted", "example": "message.redacted" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "caseId": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "messageId": { "type": "string", "example": "msg_3PqA0x8bVw1TqS9mYp3RkL" } }, "required": [ "caseId", "messageId" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "approval.requested": { "post": { "operationId": "webhooks.approval.requested", "summary": "Event approval.requested", "description": "An agent asked to run an action that its tool policy puts behind a person. Nothing ran. Decide it with POST /v2/approvals/{id}/approve or /reject before approval.expiresAt. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "approval.requested", "example": "approval.requested" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": "string" }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", null ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "automatedDecision": { "type": "boolean" }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object" } }, "requestedByKeyId": { "type": [ "string", "null" ] }, "decision": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] } ] }, "result": { "type": [ "string", "null" ] }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] } }, "required": [ "approval" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "approval.decided": { "post": { "operationId": "webhooks.approval.decided", "summary": "Event approval.decided", "description": "An approval was approved or rejected. approval.decision says by whom (a member or an API key) and why. When it was approved the action runs right after: follow approval.status. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "approval.decided", "example": "approval.decided" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": "string" }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", null ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "automatedDecision": { "type": "boolean" }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object" } }, "requestedByKeyId": { "type": [ "string", "null" ] }, "decision": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] } ] }, "result": { "type": [ "string", "null" ] }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] } }, "required": [ "approval" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "approval.expired": { "post": { "operationId": "webhooks.approval.expired", "summary": "Event approval.expired", "description": "Nobody decided in time, so the action never ran and the agent told the person. Ask the agent again if it still applies. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "approval.expired", "example": "approval.expired" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": "string" }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", null ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "automatedDecision": { "type": "boolean" }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object" } }, "requestedByKeyId": { "type": [ "string", "null" ] }, "decision": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] } ] }, "result": { "type": [ "string", "null" ] }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] } }, "required": [ "approval" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "approval.escalated": { "post": { "operationId": "webhooks.approval.escalated", "summary": "Event approval.escalated", "description": "A pending approval passed the time its policy gives before escalating (escalateAfterMinutes). Nothing changed in the approval: remind or reassign in your system before it expires. Fires once per approval. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "approval.escalated", "example": "approval.escalated" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": "string" }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", null ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "automatedDecision": { "type": "boolean" }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object" } }, "requestedByKeyId": { "type": [ "string", "null" ] }, "decision": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] } ] }, "result": { "type": [ "string", "null" ] }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] } }, "required": [ "approval" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "approval.canceled": { "post": { "operationId": "webhooks.approval.canceled", "summary": "Event approval.canceled", "description": "A pending approval was canceled because the person it is about asked to be erased. Nothing ran and it cannot be decided any more. Drop it from your queue. The approval no longer carries the arguments or the summary. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "approval.canceled", "example": "approval.canceled" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": "string" }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", null ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "automatedDecision": { "type": "boolean" }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object" } }, "requestedByKeyId": { "type": [ "string", "null" ] }, "decision": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] } ] }, "result": { "type": [ "string", "null" ] }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] } }, "required": [ "approval" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "approval.review_requested": { "post": { "operationId": "webhooks.approval.review_requested", "summary": "Event approval.review_requested", "description": "The person affected by an automated decision that went through an approval asked for a human review (Ley 21.719, art. 8 bis). Carries the reason they gave, also stored in approval.reviewReason. Review the decision and respond to the person in your system. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "approval.review_requested", "example": "approval.review_requested" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "approval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "approval" ] }, "id": { "type": "string", "example": "apr_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected", "expired", "canceled", "executing", "executed", "failed" ] }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "arguments": { "type": [ "object", "null" ], "additionalProperties": true }, "summary": { "type": "string" }, "reasonCode": { "type": [ "string", "null" ], "enum": [ "policy_always", "policy_condition", "policy_accumulated", "policy_rule", null ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "automatedDecision": { "type": "boolean" }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "approvers": { "type": "array", "items": { "type": "object" } }, "requestedByKeyId": { "type": [ "string", "null" ] }, "decision": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "decidedAt": { "type": "string", "format": "date-time" }, "by": { "type": "object" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "decidedAt", "by", "reason" ] } ] }, "result": { "type": [ "string", "null" ] }, "executedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "escalatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "agentId", "caseId", "tool", "arguments", "summary", "reasonCode", "ruleIndex", "automatedDecision", "dataSeen", "approvers", "requestedByKeyId", "decision", "result", "executedAt", "expiresAt", "escalatedAt", "reviewRequestedAt", "reviewReason", "createdAt", "updatedAt" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "approval", "reason" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "automated_decision.review_requested": { "post": { "operationId": "webhooks.automated_decision.review_requested", "summary": "Event automated_decision.review_requested", "description": "The person affected by an automated decision that no one approved asked for a human review (Ley 21.719, art. 8 bis). Carries the reason they gave, also stored in automatedDecision.reviewReason. Review the decision and respond to the person in your system. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "automated_decision.review_requested", "example": "automated_decision.review_requested" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "automatedDecision": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "automated_decision" ] }, "id": { "type": "string", "example": "dec_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "caseId": { "type": [ "string", "null" ] }, "tool": { "type": "string" }, "outcome": { "type": "string", "enum": [ "allowed", "rejected" ] }, "reasonCode": { "type": "string", "enum": [ "policy_rule", "policy_not_required" ] }, "ruleIndex": { "type": [ "integer", "null" ] }, "dataSeen": { "type": "array", "items": { "type": "string" } }, "reviewRequestedAt": { "type": [ "string", "null" ], "format": "date-time" }, "reviewReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "caseId", "tool", "outcome", "reasonCode", "ruleIndex", "dataSeen", "reviewRequestedAt", "reviewReason", "createdAt" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "automatedDecision", "reason" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "team_question.created": { "post": { "operationId": "webhooks.team_question.created", "summary": "Event team_question.created", "description": "An agent left a question for the team and keeps attending. Answer it with POST /v2/team-questions/{id}/answer; the agent resumes and tells the person. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "team_question.created", "example": "team_question.created" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "question": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team_question" ] }, "id": { "type": "string", "example": "tqn_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "open", "answered", "delivered", "discarded" ] }, "caseId": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "question": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "answeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "caseId", "question", "context", "answer", "answeredAt", "deliveredAt", "createdAt", "updatedAt" ] } }, "required": [ "question" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "team_question.answered": { "post": { "operationId": "webhooks.team_question.answered", "summary": "Event team_question.answered", "description": "A team question received its answer. The agent is about to tell the person. status moves to delivered once it did. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "team_question.answered", "example": "team_question.answered" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "question": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team_question" ] }, "id": { "type": "string", "example": "tqn_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "open", "answered", "delivered", "discarded" ] }, "caseId": { "type": "string", "example": "cse_7Hc2LmQ0x8bVw1TqS9mYp3" }, "question": { "type": "string" }, "context": { "type": [ "string", "null" ] }, "answer": { "type": [ "string", "null" ] }, "answeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "status", "caseId", "question", "context", "answer", "answeredAt", "deliveredAt", "createdAt", "updatedAt" ] } }, "required": [ "question" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "meeting.scheduled": { "post": { "operationId": "webhooks.meeting.scheduled", "summary": "Event meeting.scheduled", "description": "A meeting was booked in an agenda, by this API, the dashboard or an agent. The attendee already got the invitation. Read it with GET /v2/scheduling/meetings/{id}. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "meeting.scheduled", "example": "meeting.scheduled" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "meeting": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "example": "mtg_5RvP2aKq9XwLmN3tYbZc01" }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ] }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer" }, "timezone": { "type": "string" }, "attendeeEmail": { "type": "string" }, "attendeeName": { "type": "string" }, "attendeePhone": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "meetLink": { "type": [ "string", "null" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agendaId", "status", "start", "end", "durationMinutes", "timezone", "attendeeEmail", "attendeeName", "attendeePhone", "companyName", "context", "meetLink", "canceledAt", "cancelReason", "createdAt", "updatedAt" ] } }, "required": [ "meeting" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "meeting.rescheduled": { "post": { "operationId": "webhooks.meeting.rescheduled", "summary": "Event meeting.rescheduled", "description": "A meeting moved to another slot. meeting.start and meeting.end are the new ones; the attendee was told by the calendar. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "meeting.rescheduled", "example": "meeting.rescheduled" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "meeting": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "example": "mtg_5RvP2aKq9XwLmN3tYbZc01" }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ] }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer" }, "timezone": { "type": "string" }, "attendeeEmail": { "type": "string" }, "attendeeName": { "type": "string" }, "attendeePhone": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "meetLink": { "type": [ "string", "null" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agendaId", "status", "start", "end", "durationMinutes", "timezone", "attendeeEmail", "attendeeName", "attendeePhone", "companyName", "context", "meetLink", "canceledAt", "cancelReason", "createdAt", "updatedAt" ] } }, "required": [ "meeting" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "meeting.canceled": { "post": { "operationId": "webhooks.meeting.canceled", "summary": "Event meeting.canceled", "description": "A meeting was canceled and its slot is free again. meeting.cancelReason says why when there is one. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "meeting.canceled", "example": "meeting.canceled" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "meeting": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "meeting" ] }, "id": { "type": "string", "example": "mtg_5RvP2aKq9XwLmN3tYbZc01" }, "agendaId": { "type": "string", "example": "agd_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "scheduled", "confirmed", "completed", "canceled", "no_show", "rescheduled" ] }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "durationMinutes": { "type": "integer" }, "timezone": { "type": "string" }, "attendeeEmail": { "type": "string" }, "attendeeName": { "type": "string" }, "attendeePhone": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "context": { "type": [ "string", "null" ] }, "meetLink": { "type": [ "string", "null" ] }, "canceledAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agendaId", "status", "start", "end", "durationMinutes", "timezone", "attendeeEmail", "attendeeName", "attendeePhone", "companyName", "context", "meetLink", "canceledAt", "cancelReason", "createdAt", "updatedAt" ] } }, "required": [ "meeting" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "template.status_changed": { "post": { "operationId": "webhooks.template.status_changed", "summary": "Event template.status_changed", "description": "WhatsApp reviewed a template, or paused it. rejectionReason says why when it was rejected. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "template.status_changed", "example": "template.status_changed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "template": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "template" ] }, "id": { "type": "string", "example": "tpl_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string" }, "language": { "type": "string" }, "category": { "type": "string", "enum": [ "marketing", "utility", "authentication" ] }, "status": { "type": "string", "enum": [ "in_review", "approved", "rejected", "paused" ] }, "rejectionReason": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "language", "category", "status", "rejectionReason" ] }, "previousStatus": { "type": "string", "enum": [ "in_review", "approved", "rejected", "paused" ] } }, "required": [ "template", "previousStatus" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "campaign.status_changed": { "post": { "operationId": "webhooks.campaign.status_changed", "summary": "Event campaign.status_changed", "description": "A campaign started, paused, resumed, completed or was canceled. pauseReason says why it paused by itself, if it did. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "campaign.status_changed", "example": "campaign.status_changed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "campaign": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "campaign" ] }, "id": { "type": "string", "example": "cmp_3PqA0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled" ] }, "pauseReason": { "type": [ "string", "null" ] } }, "required": [ "object", "id", "name", "status", "pauseReason" ] }, "previousStatus": { "type": [ "string", "null" ], "enum": [ "draft", "scheduled", "sending", "paused", "completed", "canceled", null ] } }, "required": [ "campaign", "previousStatus" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "trigger.attempted": { "post": { "operationId": "webhooks.trigger.attempted", "summary": "Event trigger.attempted", "description": "An attempt of a trigger cadence ran, or the cadence ended. result is sent when a template message was queued, skipped when the attempt could not go out (reason says why and the cadence ends), or stopped when the contact replied, opted out, or the case changed stage or closed (reason says which). Fires once per attempt, and once more when a cadence is stopped. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "trigger.attempted", "example": "trigger.attempted" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "triggerId": { "type": "string", "example": "trg_1Qa0x8bVw1TqS9mYp3RkLd" }, "contactId": { "type": "string", "example": "ctc_3PqA0x8bVw1TqS9mYp3RkL" }, "caseId": { "type": [ "string", "null" ] }, "attempt": { "type": "integer" }, "attempts": { "type": "integer" }, "result": { "type": "string", "enum": [ "sent", "skipped", "stopped" ] }, "reason": { "type": [ "string", "null" ] }, "messageId": { "type": [ "string", "null" ] }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "triggerId", "contactId", "caseId", "attempt", "attempts", "result", "reason", "messageId", "nextAttemptAt" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "copilot.turn": { "post": { "operationId": "webhooks.copilot.turn", "summary": "Event copilot.turn", "description": "Progress of a copilot turn: its status, or one of its steps. `kind` tells which. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "copilot.turn", "example": "copilot.turn" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "kind": { "type": "string", "enum": [ "status", "step" ] }, "userId": { "type": [ "string", "null" ] }, "turnId": { "type": [ "string", "null" ] }, "seq": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "running", "finished", "stopped", "failed" ] }, "messageIds": { "type": "array", "items": { "type": "string" } }, "order": { "type": "integer" }, "slug": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "read", "write" ] }, "stepStatus": { "type": "string", "enum": [ "running", "done", "failed" ] } }, "required": [ "kind", "userId", "turnId", "seq" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "run.started": { "post": { "operationId": "webhooks.run.started", "summary": "Event run.started", "description": "A worker picked up a run and the agent started working on it. It carries the run. It is sent at least once, so a run that a worker lost halfway can announce it again. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "run.started", "example": "run.started" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "run.waiting_for_answer": { "post": { "operationId": "webhooks.run.waiting_for_answer", "summary": "Event run.waiting_for_answer", "description": "The agent paused the run to ask a person. run.question has the question; answer it with POST /v2/runs/{id}/answer and the run resumes. A run nobody answers within 30 days ends failed with stopReason abandoned. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "run.waiting_for_answer", "example": "run.waiting_for_answer" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "run.completed": { "post": { "operationId": "webhooks.run.completed", "summary": "Event run.completed", "description": "The agent declared the job done. run.status is completed_unverified: nobody has checked it yet, so read run.result.summary and run.result.checks before you trust it. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "run.completed", "example": "run.completed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "run.stopped": { "post": { "operationId": "webhooks.run.stopped", "summary": "Event run.stopped", "description": "The run was cut before the agent declared the job done. run.stopReason says why (rounds, time or cost: a limit ran out; no_conclusion: the agent never called its finish action; loop: the agent repeated itself) and run.result.partial keeps the last thing the agent wrote. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "run.stopped", "example": "run.stopped" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "run.failed": { "post": { "operationId": "webhooks.run.failed", "summary": "Event run.failed", "description": "The run ended with an error, or nobody answered its question in 30 days (stopReason abandoned). run.result.error says what happened. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "run.failed", "example": "run.failed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "run.canceled": { "post": { "operationId": "webhooks.run.canceled", "summary": "Event run.canceled", "description": "The run was canceled: nothing else will run. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "run.canceled", "example": "run.canceled" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "schedule.fired": { "post": { "operationId": "webhooks.schedule.fired", "summary": "Event schedule.fired", "description": "A scheduled task reached its date and started a run. It carries the schedule and the run. A date the service missed is not replayed: the task fires once and moves to its next date. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "schedule.fired", "example": "schedule.fired" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "schedule": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "schedule" ] }, "id": { "type": "string", "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "contactId": { "type": "string", "example": "ctc_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string" }, "cron": { "type": "string" }, "timezone": { "type": "string" }, "goal": { "type": "string" }, "channel": { "type": "string", "enum": [ "email" ] }, "from": { "type": [ "string", "null" ] }, "onReply": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "instructions": { "type": "string" } }, "required": [ "instructions" ] } ] }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "enabled": { "type": "boolean" }, "pausedReason": { "type": [ "string", "null" ] }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "contactId", "name", "cron", "timezone", "goal", "channel", "from", "onReply", "limits", "enabled", "pausedReason", "nextRunAt", "lastRunAt", "createdAt", "updatedAt" ] }, "run": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "run" ] }, "id": { "type": "string", "example": "run_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "status": { "type": "string", "enum": [ "running", "waiting_for_answer", "completed_unverified", "stopped", "failed", "canceled" ] }, "stopReason": { "type": [ "string", "null" ], "enum": [ "rounds", "cost", "time", "no_conclusion", "loop", "abandoned", null ], "description": "rounds: the run used all the rounds allowed by limits.maxRounds. cost: the run reached the spending limit Lelemon sets for every run. time: the run lasted all the minutes allowed by limits.maxMinutes. no_conclusion: the agent answered four times in a row without calling its finish action, so it never declared the job done. Its last answer is in result.partial. loop: the agent kept repeating the same action, so the run was cut. abandoned: with status failed: the agent asked a question and nobody answered it in 30 days." }, "question": { "type": [ "string", "null" ] }, "rounds": { "type": "integer" }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "result": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "summary": { "type": "string" }, "checks": { "type": "array", "items": { "type": "string" } }, "partial": { "type": "string" }, "error": { "type": "string" }, "errorCode": { "type": "string" } }, "required": [] } ] }, "cancelRequested": { "type": "boolean" }, "schedule": { "type": [ "string", "null" ], "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "actor": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string", "enum": [ "end_user", "staff", "admin" ] }, "declaredBy": { "type": "string" } }, "required": [ "id", "role", "declaredBy" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": [ "string", "null" ], "format": "date-time" }, "finishedAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "status", "stopReason", "question", "rounds", "limits", "result", "cancelRequested", "schedule", "actor", "createdAt", "startedAt", "finishedAt", "updatedAt" ] } }, "required": [ "schedule", "run" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "schedule.skipped": { "post": { "operationId": "webhooks.schedule.skipped", "summary": "Event schedule.skipped", "description": "A scheduled task reached its date and did not start a run. reason says why: opted_out (the contact opted out of email), recipient_not_allowed (the contact is not in the recipient allowlist), agent_unavailable (the agent is paused, deleted or has no email channel) or contact_unavailable (the contact no longer exists or has no email). The task keeps its schedule and fires on its next date. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "schedule.skipped", "example": "schedule.skipped" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "schedule": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "schedule" ] }, "id": { "type": "string", "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "contactId": { "type": "string", "example": "ctc_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string" }, "cron": { "type": "string" }, "timezone": { "type": "string" }, "goal": { "type": "string" }, "channel": { "type": "string", "enum": [ "email" ] }, "from": { "type": [ "string", "null" ] }, "onReply": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "instructions": { "type": "string" } }, "required": [ "instructions" ] } ] }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "enabled": { "type": "boolean" }, "pausedReason": { "type": [ "string", "null" ] }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "contactId", "name", "cron", "timezone", "goal", "channel", "from", "onReply", "limits", "enabled", "pausedReason", "nextRunAt", "lastRunAt", "createdAt", "updatedAt" ] }, "reason": { "type": "string", "enum": [ "opted_out", "recipient_not_allowed", "agent_unavailable", "contact_unavailable" ] } }, "required": [ "schedule", "reason" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "schedule.paused": { "post": { "operationId": "webhooks.schedule.paused", "summary": "Event schedule.paused", "description": "A scheduled task was paused by the platform after three runs in a row that failed or were cut. reason is consecutive_failures. Fix the cause and turn it on again with PATCH /v2/schedules/{id} and enabled true. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "schedule.paused", "example": "schedule.paused" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "schedule": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "schedule" ] }, "id": { "type": "string", "example": "sch_5RvP2aKq9XwLmN3tYbZc01" }, "agentId": { "type": "string", "example": "agt_5RvP2aKq9XwLmN3tYbZc01" }, "contactId": { "type": "string", "example": "ctc_5RvP2aKq9XwLmN3tYbZc01" }, "name": { "type": "string" }, "cron": { "type": "string" }, "timezone": { "type": "string" }, "goal": { "type": "string" }, "channel": { "type": "string", "enum": [ "email" ] }, "from": { "type": [ "string", "null" ] }, "onReply": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "instructions": { "type": "string" } }, "required": [ "instructions" ] } ] }, "limits": { "type": "object", "properties": { "maxRounds": { "type": "integer" }, "maxMinutes": { "type": "integer" } }, "required": [ "maxRounds", "maxMinutes" ] }, "enabled": { "type": "boolean" }, "pausedReason": { "type": [ "string", "null" ] }, "nextRunAt": { "type": "string", "format": "date-time" }, "lastRunAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "agentId", "contactId", "name", "cron", "timezone", "goal", "channel", "from", "onReply", "limits", "enabled", "pausedReason", "nextRunAt", "lastRunAt", "createdAt", "updatedAt" ] }, "reason": { "type": "string", "enum": [ "consecutive_failures" ] } }, "required": [ "schedule", "reason" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "knowledge_document.ready": { "post": { "operationId": "webhooks.knowledge_document.ready", "summary": "Event knowledge_document.ready", "description": "A document finished processing and the agents that have its collection can search it. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "knowledge_document.ready", "example": "knowledge_document.ready" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "document": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_document" ] }, "id": { "type": "string", "example": "kbd_02y0e5MANqacVbmtn1YyeJ" }, "collectionId": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "chunkCount": { "type": "integer" }, "error": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "collectionId", "name", "mimeType", "sizeBytes", "status", "chunkCount", "error", "createdAt", "updatedAt" ] } }, "required": [ "document" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "knowledge_document.failed": { "post": { "operationId": "webhooks.knowledge_document.failed", "summary": "Event knowledge_document.failed", "description": "A document could not be processed. document.error.code says why. The collection keeps working; upload the document again to retry. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "knowledge_document.failed", "example": "knowledge_document.failed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "document": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "knowledge_document" ] }, "id": { "type": "string", "example": "kbd_02y0e5MANqacVbmtn1YyeJ" }, "collectionId": { "type": "string", "example": "kbc_2LpX0x8bVw1TqS9mYp3RkL" }, "name": { "type": "string" }, "mimeType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "processing", "ready", "failed" ] }, "chunkCount": { "type": "integer" }, "error": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "collectionId", "name", "mimeType", "sizeBytes", "status", "chunkCount", "error", "createdAt", "updatedAt" ] } }, "required": [ "document" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "phone_number.connected": { "post": { "operationId": "webhooks.phone_number.connected", "summary": "Event phone_number.connected", "description": "A subaccount linked its WhatsApp number and its agent started answering on it. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "phone_number.connected", "example": "phone_number.connected" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "phoneNumber": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "phone_number" ] }, "id": { "type": "string", "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd" }, "phone": { "type": [ "string", "null" ] }, "verifiedName": { "type": [ "string", "null" ] }, "agentId": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "phone", "verifiedName", "agentId", "active", "createdAt", "updatedAt" ] }, "connectionId": { "type": "string" } }, "required": [ "phoneNumber", "connectionId" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "phone_number.connection_failed": { "post": { "operationId": "webhooks.phone_number.connection_failed", "summary": "Event phone_number.connection_failed", "description": "The number linked is not the one requested, or it belongs to another account. Nothing was attached; connection.failure.code says why. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "phone_number.connection_failed", "example": "phone_number.connection_failed" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "connection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "whatsapp_connection" ] }, "id": { "type": "string", "example": "wcn_4Zq0x8bVw1TqS9mYp3RkLd" }, "phone": { "type": "string" }, "agentId": { "type": [ "string", "null" ] }, "connectionType": { "type": "string", "enum": [ "coexistence", "dedicated" ] }, "status": { "type": "string" }, "setupUrl": { "type": [ "string", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "phoneNumberId": { "type": [ "string", "null" ] }, "failure": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "phone", "agentId", "connectionType", "status", "setupUrl", "expiresAt", "phoneNumberId", "failure", "createdAt", "updatedAt" ] } }, "required": [ "connection" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "phone_number.disconnected": { "post": { "operationId": "webhooks.phone_number.disconnected", "summary": "Event phone_number.disconnected", "description": "A WhatsApp number was disconnected, by you or by the provider. Its agent no longer answers on it. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "phone_number.disconnected", "example": "phone_number.disconnected" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "phoneNumber": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "phone_number" ] }, "id": { "type": "string", "example": "pn_4Zq0x8bVw1TqS9mYp3RkLd" }, "phone": { "type": [ "string", "null" ] }, "verifiedName": { "type": [ "string", "null" ] }, "agentId": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "object", "id", "phone", "verifiedName", "agentId", "active", "createdAt", "updatedAt" ] } }, "required": [ "phoneNumber" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "webhook_endpoint.test": { "post": { "operationId": "webhooks.webhook_endpoint.test", "summary": "Event webhook_endpoint.test", "description": "Sent by POST /v2/webhook-endpoints/{id}/test to check that an endpoint receives and verifies events. Lelemon sends it to the webhook endpoints subscribed to this type, signed in the Lelemon-Signature header. Answer with any 2xx within 10 seconds; anything else is retried.", "tags": [ "Webhook endpoints" ], "security": [ { "webhook-signature": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "event" ] }, "id": { "type": "string", "example": "evt_3PqA0x8bVw1TqS9mYp3RkL" }, "type": { "type": "string", "description": "The event type, such as case.escalated. See GET /v2/event-types.", "const": "webhook_endpoint.test", "example": "webhook_endpoint.test" }, "createdAt": { "type": "string", "format": "date-time" }, "organizationId": { "type": "string", "example": "org_7Hc2LmQ0x8bVw1TqS9mYp3" }, "customerId": { "type": "string", "example": "sub_7Hc2LmQ0x8bVw1TqS9mYp3", "description": "The subaccount the event belongs to, when there is one." }, "data": { "type": "object", "additionalProperties": true, "description": "The shape depends on `type`. See GET /v2/event-types.", "properties": { "endpointId": { "type": "string", "example": "whk_3PqA0x8bVw1TqS9mYp3RkL" }, "message": { "type": "string" } }, "required": [ "endpointId", "message" ] } }, "required": [ "object", "id", "type", "createdAt", "organizationId", "data" ] } } } }, "responses": { "2XX": { "description": "The event was received." } } } }, "connector.manifest": { "get": { "operationId": "webhooks.connector.manifest", "summary": "Connector manifest", "description": "GET {baseUrl}/manifest. Lelemon calls it when you check the connector. Answer with the name of your system and the views the copilot can read. Every call carries a Lelemon-Signature header: verify it with verifyRequest of the SDK, domain connector. The format is lelemon-connector/v1; see GET /v2/data-connectors/format.", "tags": [ "Data connectors" ], "security": [ { "connector-signature": [] } ], "responses": { "200": { "description": "The answer in the connector format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorManifest" } } } } } } }, "connector.accounts.search": { "get": { "operationId": "webhooks.connector.accounts.search", "summary": "Search accounts", "description": "GET {baseUrl}/accounts. Lelemon calls it to find the accounts of a person by email. Answer one page of account cards. Every call carries a Lelemon-Signature header: verify it with verifyRequest of the SDK, domain connector. The format is lelemon-connector/v1; see GET /v2/data-connectors/format.", "tags": [ "Data connectors" ], "security": [ { "connector-signature": [] } ], "parameters": [ { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 320 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_=.-]{1,500}$" }, "description": "The nextCursor of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The answer in the connector format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorAccountSearch" } } } } } } }, "connector.accounts.retrieve": { "get": { "operationId": "webhooks.connector.accounts.retrieve", "summary": "Read an account", "description": "GET {baseUrl}/accounts/{id}. Lelemon calls it to read one account card. Every call carries a Lelemon-Signature header: verify it with verifyRequest of the SDK, domain connector. The format is lelemon-connector/v1; see GET /v2/data-connectors/format.", "tags": [ "Data connectors" ], "security": [ { "connector-signature": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9._~-]{1,128}$" } } ], "responses": { "200": { "description": "The answer in the connector format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorAccount" } } } } } } }, "connector.views.read": { "get": { "operationId": "webhooks.connector.views.read", "summary": "Read a view", "description": "GET {baseUrl}/views/{viewId}. Lelemon calls it to read one page of a view declared in the manifest. The filters of the view arrive as extra query parameters. Every call carries a Lelemon-Signature header: verify it with verifyRequest of the SDK, domain connector. The format is lelemon-connector/v1; see GET /v2/data-connectors/format.", "tags": [ "Data connectors" ], "security": [ { "connector-signature": [] } ], "parameters": [ { "name": "viewId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_=.-]{1,500}$" }, "description": "The nextCursor of the previous page." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "The answer in the connector format.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorView" } } } } } } } } }