{"openapi":"3.1.0","jsonSchemaDialect":"https://spec.openapis.org/oas/3.1/dialect/base","info":{"title":"HelpVox API","version":"1.0.0","description":"The HelpVox REST API: orders, catalogue, conversations, customer requests, knowledge and settings of one company.\n\n## Authentication\n\nEvery call carries `Authorization: Bearer <token>`. Three kinds of token are accepted:\n\n- **API key** `hv_live_…` — created in the dashboard or with `POST /api-keys`. Belongs to the company and may call everything.\n- **App installation token** `hva_…` — issued to an app by `POST /api/oauth/token` when a merchant installs it. Limited to the scopes the merchant approved; never gets `team:read` or `team:write`.\n- **MCP OAuth token** `hvo_…` — an MCP client approved by a person. Its `read` scope covers every `*:read`; write scopes have the same names as below, plus `team:write`.\n\nEach operation lists its scope in `x-required-scope` (null = any valid token). A call without it returns\n`403 {\"error\":{\"code\":\"insufficient_scope\",\"scope\":\"orders:read\"}}`.\n\n## Scopes\n\n| Scope | Grants | Personal data |\n| --- | --- | --- |\n| `catalog:read` | products, variants, categories, stock | no |\n| `orders:read` | orders and their events, **without** customer fields | no |\n| `customers:read` | customer name/phone/email/address on orders, calls, callbacks, appointments | yes |\n| `conversations:read` | calls and chats: duration, outcome, analysis — no text | no |\n| `transcripts:read` | full transcript and analysis summary | yes |\n| `requests:read` | callback requests and appointments | no |\n| `knowledge:read` | knowledge base, company profile | no |\n| `account:read` | markets, hours, agents, shop connection | no |\n| `orders:write` | change orders, add shipment events, create orders, order discounts | no |\n| `requests:write` | resolve callbacks, move appointments | no |\n| `knowledge:write` | replace the knowledge base | no |\n| `products:write` | create/update/delete products and prices | no |\n| `profile:write` | change the company profile | no |\n| `settings:write` | change settings | no |\n| `agent:tools` | declare tools for the agent | no |\n\n## Personal data\n\nWithout `customers:read`, customer fields are **removed** from responses (not set to null). Without\n`transcripts:read`, `transcript` and `analysis.summary` are removed from calls. Such fields are optional in the\nschemas and marked with `x-personal-data`.\n\n## Conventions\n\n- Errors: `{ \"error\": { \"code\": \"…\", \"message\": \"…\" } }`.\n- Lists: `?limit=&offset=` and a `meta` object `{ total, limit, offset, has_more }`.\n- Money from the database is a decimal string (`\"49.90\"`); prices of variants and markets are numbers.\n- Rate limit: 1000 requests per minute per token and endpoint; `x-ratelimit-limit`, `x-ratelimit-remaining`,\n  `x-ratelimit-reset` on every response, 429 `rate_limited` with `retry-after` when exceeded.","contact":{"name":"HelpVox","url":"https://www.helpvox.ai"}},"servers":[{"url":"https://www.helpvox.ai/api/v1"}],"security":[{"apiKey":[]},{"appToken":[]},{"mcpToken":[]}],"tags":[{"name":"Account"},{"name":"Orders"},{"name":"Catalog"},{"name":"Conversations"},{"name":"Requests","description":"Callback requests and appointments."},{"name":"Knowledge","description":"FAQ and company profile."},{"name":"Settings"},{"name":"Team","description":"Not available to apps."},{"name":"App","description":"Only for app installation tokens."},{"name":"Discounts","description":"Order discounts an app attaches during a conversation."},{"name":"Events","description":"Webhooks HelpVox sends to an app."},{"name":"Agent tools","description":"Calls HelpVox makes to an app's agent tools."}],"paths":{"/me":{"get":{"operationId":"getMe","tags":["Account"],"summary":"Company the token belongs to, usage, numbers and agents","description":"Any valid token.","x-required-scope":null,"security":[{"apiKey":[]},{"appToken":[]},{"mcpToken":[]}],"responses":{"200":{"description":"Account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/orders":{"get":{"operationId":"listOrders","tags":["Orders"],"summary":"List orders, newest first","description":"Requires `orders:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"orders:read","security":[{"apiKey":[]},{"appToken":["orders:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"},"description":"One of `new`, `processing`, `prepared`, `in_transit`, `delivery_failed`, `delivered`, `cancelled`, `returned`. Older integrations may still send `packed`, `shipped` and `return_requested`; they are stored as the new names."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size (default 50, max 200)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of orders.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["meta","orders"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createOrder","tags":["Orders"],"summary":"Push an order from your shop, WMS or ERP","description":"The agent then answers about it like about its own orders. Items are snapshots; a `sku` that matches a catalogue variant links the item to it. Idempotent by `external_ref`: a repeat returns 200 with `created: false`.\n\nRequires `orders:write`. API keys may call everything.","x-required-scope":"orders:write","security":[{"apiKey":[]},{"appToken":["orders:write"]},{"mcpToken":["orders:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrder"}}}},"responses":{"200":{"description":"An order with this `external_ref` already exists.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","const":false},"id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"external_ref":{"type":["string","null"]}},"required":["created","id","order_number","external_ref"]}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"external_ref":{"type":["string","null"]},"total":{"type":"string","description":"Total with currency, e.g. \"49.90 EUR\"."}},"required":["created","id","order_number","external_ref","total"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/orders/{id}":{"get":{"operationId":"getOrder","tags":["Orders"],"summary":"Get one order","description":"Requires `orders:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"orders:read","security":[{"apiKey":[]},{"appToken":["orders:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order UUID, short `order_number`, or your `external_ref`."}],"responses":{"200":{"description":"The order — the same shape as an entry of `GET /orders`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateOrder","tags":["Orders"],"summary":"Update status, tracking, courier or payment status","description":"Status changes follow the same transitions as the dashboard; an illegal one returns 409 `invalid_transition`. At least one field is required.\n\nRequires `orders:write`. API keys may call everything.","x-required-scope":"orders:write","security":[{"apiKey":[]},{"appToken":["orders:write"]},{"mcpToken":["orders:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order UUID, short `order_number`, or your `external_ref`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"One of `new`, `processing`, `prepared`, `in_transit`, `delivery_failed`, `delivered`, `cancelled`, `returned`. Older integrations may still send `packed`, `shipped` and `return_requested`; they are stored as the new names.","enum":["new","processing","prepared","in_transit","delivery_failed","delivered","cancelled","returned","packed","shipped","return_requested"]},"tracking_number":{"type":"string","maxLength":80},"courier":{"type":"string","maxLength":60},"courier_service":{"type":"string","maxLength":60},"payment_status":{"type":"string","enum":["pending","collected","paid_out"]}},"minProperties":1}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"order_number":{"type":"string"},"status":{"type":"string","description":"As sent, or the unchanged status."}},"required":["ok","order_number","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`invalid_transition` — the status cannot move from the current one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/orders/{id}/events":{"get":{"operationId":"listOrderEvents","tags":["Orders"],"summary":"Delivery checkpoints, oldest first","description":"Requires `orders:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"orders:read","security":[{"apiKey":[]},{"appToken":["orders:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order UUID, short `order_number`, or your `external_ref`."}],"responses":{"200":{"description":"Checkpoints.","content":{"application/json":{"schema":{"type":"object","properties":{"order_number":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/OrderEvent"}}},"required":["order_number","events"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"addOrderEvents","tags":["Orders"],"summary":"Push delivery checkpoints","description":"One event, or `{ events: [...] }` (up to 100). Duplicates (same order, time and description) are ignored, so full re-syncs are safe.\n\nRequires `orders:write`. API keys may call everything.","x-required-scope":"orders:write","security":[{"apiKey":[]},{"appToken":["orders:write"]},{"mcpToken":["orders:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Order UUID, short `order_number`, or your `external_ref`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/OrderEventInput"},{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/OrderEventInput"},"minItems":1,"maxItems":100}},"required":["events"]}]}}}},"responses":{"200":{"description":"Stored.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"received":{"type":"integer"},"inserted":{"type":"integer","description":"New ones; the rest were duplicates."}},"required":["ok","received","inserted"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products":{"get":{"operationId":"listProducts","tags":["Catalog"],"summary":"List products with their variants, by external_id","description":"Requires `catalog:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"catalog:read","security":[{"apiKey":[]},{"appToken":["catalog:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Page size (default 100, max 500)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of products.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer","description":"Same as `meta.total` (kept for older integrations)."},"meta":{"$ref":"#/components/schemas/Meta"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}},"required":["total","meta","products"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createProducts","tags":["Catalog"],"summary":"Create products (one, or `{ products: [...] }`)","description":"An existing `external_id` is an error (409 `already_exists`), not an overwrite — use PUT to update. The same `external_id` twice in one request is 422 `duplicate_external_id`. Both errors list the ids in `error.external_ids`.\n\nRequires `products:write`. API keys may call everything.","x-required-scope":"products:write","security":[{"apiKey":[]},{"appToken":["products:write"]},{"mcpToken":["products:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProductInput"},{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductInput"},"minItems":1,"maxItems":500}},"required":["products"]}]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`already_exists`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`validation_error` or `duplicate_external_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"upsertProducts","tags":["Catalog"],"summary":"Create or update products by external_id","description":"Requires `products:write`. API keys may call everything.","x-required-scope":"products:write","security":[{"apiKey":[]},{"appToken":["products:write"]},{"mcpToken":["products:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductInput"},"minItems":1,"maxItems":500}},"required":["products"]}}}},"responses":{"200":{"description":"Upserted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/products/{external_id}":{"get":{"operationId":"getProduct","tags":["Catalog"],"summary":"Get one product by your external_id","description":"Requires `catalog:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"catalog:read","security":[{"apiKey":[]},{"appToken":["catalog:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your product identifier."}],"responses":{"200":{"description":"The product.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteProduct","tags":["Catalog"],"summary":"Delete a product and its variants","description":"Requires `products:write`. API keys may call everything.","x-required-scope":"products:write","security":[{"apiKey":[]},{"appToken":["products:write"]},{"mcpToken":["products:write"]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your product identifier."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true}},"required":["deleted"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/categories":{"get":{"operationId":"listCategories","tags":["Catalog"],"summary":"All categories, flat, parents before children","description":"Requires `catalog:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"catalog:read","security":[{"apiKey":[]},{"appToken":["catalog:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Categories.","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["total","categories"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createCategory","tags":["Catalog"],"summary":"Create a category by name (+ parent) or by full path","description":"A `path` that already exists returns it with 200 and `created: false`, so repeated imports do not fail.\n\nRequires `products:write`. API keys may call everything.","x-required-scope":"products:write","security":[{"apiKey":[]},{"appToken":["products:write"]},{"mcpToken":["products:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Name of the new category under `parent_id` (or at the root).","minLength":1,"maxLength":120},"parent_id":{"type":["string","null"],"format":"uuid"},"path":{"type":"string","description":"Or a whole path, e.g. \"Audio / Headphones\"; missing levels are created.","minLength":1,"maxLength":1200}},"description":"Give either `name` (with optional `parent_id`) or `path`."}}}},"responses":{"200":{"description":"The path already existed.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","const":false},"category":{"$ref":"#/components/schemas/Category"}},"required":["created","category"]}}}},"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean","const":true},"category":{"$ref":"#/components/schemas/Category"}},"required":["created","category"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/categories/{id}":{"patch":{"operationId":"updateCategory","tags":["Catalog"],"summary":"Rename and/or move a category","description":"Requires `products:write`. API keys may call everything.","x-required-scope":"products:write","security":[{"apiKey":[]},{"appToken":["products:write"]},{"mcpToken":["products:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Category id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"parent_id":{"type":["string","null"],"description":"`null` moves it to the root.","format":"uuid"}},"minProperties":1}}}},"responses":{"200":{"description":"Updated; paths of the subtree are recomputed.","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"$ref":"#/components/schemas/Category"}},"required":["category"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"deleteCategory","tags":["Catalog"],"summary":"Delete an empty category","description":"Requires `products:write`. API keys may call everything.","x-required-scope":"products:write","security":[{"apiKey":[]},{"appToken":["products:write"]},{"mcpToken":["products:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Category id."}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true}},"required":["deleted"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`category_not_empty` — `error.products` is how many products are in it or below it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/calls":{"get":{"operationId":"listCalls","tags":["Conversations"],"summary":"List calls and chats with a short analysis, newest first","description":"Requires `conversations:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"conversations:read","security":[{"apiKey":[]},{"appToken":["conversations:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size (default 50, max 200)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of calls.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"calls":{"type":"array","items":{"$ref":"#/components/schemas/Call"}}},"required":["meta","calls"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/calls/{id}":{"get":{"operationId":"getCall","tags":["Conversations"],"summary":"One call with transcript and full analysis","description":"Requires `conversations:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"conversations:read","security":[{"apiKey":[]},{"appToken":["conversations:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Call id."}],"responses":{"200":{"description":"The call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/callbacks":{"get":{"operationId":"listCallbacks","tags":["Requests"],"summary":"Callback requests taken by the agent, newest first","description":"Requires `requests:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"requests:read","security":[{"apiKey":[]},{"appToken":["requests:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","done"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Page size (default 100, max 500)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of callback requests.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"callbacks":{"type":"array","items":{"$ref":"#/components/schemas/Callback"}}},"required":["meta","callbacks"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/callbacks/{id}":{"patch":{"operationId":"updateCallback","tags":["Requests"],"summary":"Mark a callback done (or pending again), with an optional outcome","description":"Requires `requests:write`. API keys may call everything.","x-required-scope":"requests:write","security":[{"apiKey":[]},{"appToken":["requests:write"]},{"mcpToken":["requests:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Callback request id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","done"]},"outcome":{"type":"string","description":"Empty string clears it.","maxLength":300}},"minProperties":1}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["ok","id","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/appointments":{"get":{"operationId":"listAppointments","tags":["Requests"],"summary":"Appointment requests taken by the agent, newest first","description":"Requires `requests:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"requests:read","security":[{"apiKey":[]},{"appToken":["requests:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["requested","confirmed","cancelled","done"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Page size (default 50, max 200)."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of appointments.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/Meta"},"appointments":{"type":"array","items":{"$ref":"#/components/schemas/Appointment"}}},"required":["meta","appointments"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/appointments/{id}":{"patch":{"operationId":"updateAppointment","tags":["Requests"],"summary":"Confirm, move, finish or cancel an appointment","description":"`confirmed_for` is required when confirming an appointment that has no time yet.\n\nRequires `requests:write`. API keys may call everything.","x-required-scope":"requests:write","security":[{"apiKey":[]},{"appToken":["requests:write"]},{"mcpToken":["requests:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Appointment id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["requested","confirmed","cancelled","done"]},"confirmed_for":{"type":"string","description":"ISO 8601, with or without an offset.","format":"date-time"},"outcome":{"type":"string","description":"Empty string clears it.","maxLength":300}},"minProperties":1}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["ok","id","status"]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/knowledge":{"get":{"operationId":"listKnowledge","tags":["Knowledge"],"summary":"FAQ entries (up to 500)","description":"Requires `knowledge:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"knowledge:read","security":[{"apiKey":[]},{"appToken":["knowledge:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Entries.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeItem"}}},"required":["items"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"replaceKnowledge","tags":["Knowledge"],"summary":"Replace the whole knowledge base","description":"Full sync, atomically. An empty list is refused — deleting everything is done in the dashboard.\n\nRequires `knowledge:write`. API keys may call everything.","x-required-scope":"knowledge:write","security":[{"apiKey":[]},{"appToken":["knowledge:write"]},{"mcpToken":["knowledge:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeInput"}}}},"responses":{"200":{"description":"Replaced.","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"}},"required":["count"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"addKnowledge","tags":["Knowledge"],"summary":"Append entries without touching the rest","description":"Requires `knowledge:write`. API keys may call everything.","x-required-scope":"knowledge:write","security":[{"apiKey":[]},{"appToken":["knowledge:write"]},{"mcpToken":["knowledge:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeInput"}}}},"responses":{"201":{"description":"Added.","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"integer"},"ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["added","ids"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/profile":{"get":{"operationId":"getProfile","tags":["Knowledge"],"summary":"Company profile the agent answers from","description":"Requires `knowledge:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"knowledge:read","security":[{"apiKey":[]},{"appToken":["knowledge:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateProfile","tags":["Knowledge"],"summary":"Change only the profile fields you send","description":"Merged, not replaced. The live agents are updated in the background after the response.\n\nRequires `profile:write`. API keys may call everything.","x-required-scope":"profile:write","security":[{"apiKey":[]},{"appToken":["profile:write"]},{"mcpToken":["profile:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"description":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":5000},"address":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"working_hours":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"delivery":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"returns":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"payment":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"contacts":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"promotions":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"digital_delivery":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":2000},"playbook":{"type":["string","null"],"description":"Empty string or null clears it.","maxLength":8000}},"minProperties":1}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Profile"},{"type":"object","properties":{"agents_updating":{"type":"boolean","const":true}},"required":["agents_updating"]}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/settings":{"get":{"operationId":"getSettings","tags":["Settings"],"summary":"Home market, dashboard language, test mode, plan","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralSettings"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateSettings","tags":["Settings"],"summary":"Switch test mode, change the home market or dashboard language","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"test_mode":{"type":"boolean"},"base_country":{"type":"string","minLength":2,"maxLength":2},"base_currency":{"type":"string","minLength":3,"maxLength":3},"base_language":{"type":"string","minLength":2,"maxLength":5}},"minProperties":1}}}},"responses":{"200":{"description":"Updated settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneralSettings"}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/markets":{"get":{"operationId":"listMarkets","tags":["Settings"],"summary":"Countries the company delivers to, with delivery terms","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Markets.","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["markets"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"replaceMarkets","tags":["Settings"],"summary":"Replace the whole list; a market left out is removed","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/MarketInput"},"maxItems":100}},"required":["markets"]}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["markets"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/hours":{"get":{"operationId":"listHours","tags":["Settings"],"summary":"Weekly opening hours for bookings (weekday 0 = Monday)","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Hours.","content":{"application/json":{"schema":{"type":"object","properties":{"hours":{"type":"array","items":{"$ref":"#/components/schemas/HoursBand"}}},"required":["hours"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"replaceHours","tags":["Settings"],"summary":"Replace the whole week; an empty list clears the hours","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hours":{"type":"array","items":{"$ref":"#/components/schemas/HoursBand"},"maxItems":28}},"required":["hours"]}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","properties":{"hours":{"type":"array","items":{"$ref":"#/components/schemas/HoursBand"}}},"required":["hours"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/resources":{"get":{"operationId":"listResources","tags":["Settings"],"summary":"People, chairs or rooms appointments are booked against","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Active resources.","content":{"application/json":{"schema":{"type":"object","properties":{"resources":{"type":"array","items":{"$ref":"#/components/schemas/Resource"}}},"required":["resources"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createResource","tags":["Settings"],"summary":"Add a resource","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120}},"required":["name"]}}}},"responses":{"201":{"description":"Added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Resource"}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/resources/{id}":{"delete":{"operationId":"deleteResource","tags":["Settings"],"summary":"Stop booking against a resource; existing appointments stay","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Resource id."}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","const":true}},"required":["removed"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/time-off":{"get":{"operationId":"listTimeOff","tags":["Settings"],"summary":"Closed periods the agent will not book in","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Closed periods.","content":{"application/json":{"schema":{"type":"object","properties":{"time_off":{"type":"array","items":{"$ref":"#/components/schemas/TimeOff"}}},"required":["time_off"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createTimeOff","tags":["Settings"],"summary":"Add a closed period","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starts_at":{"type":"string","description":"ISO 8601.","format":"date-time"},"ends_at":{"type":"string","description":"ISO 8601, after `starts_at`.","format":"date-time"},"reason":{"type":["string","null"],"maxLength":200}},"required":["starts_at","ends_at"]}}}},"responses":{"201":{"description":"Added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimeOff"}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/time-off/{id}":{"delete":{"operationId":"deleteTimeOff","tags":["Settings"],"summary":"Reopen a closed period","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Closed period id."}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","const":true}},"required":["removed"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/pronunciations":{"get":{"operationId":"listPronunciations","tags":["Settings"],"summary":"How the agent says brand names and foreign words","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Dictionary.","content":{"application/json":{"schema":{"type":"object","properties":{"pronunciations":{"type":"array","items":{"$ref":"#/components/schemas/Pronunciation"}}},"required":["pronunciations"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"put":{"operationId":"replacePronunciations","tags":["Settings"],"summary":"Replace the whole dictionary and apply it to every agent","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pronunciations":{"type":"array","items":{"type":"object","properties":{"word":{"type":"string","minLength":1,"maxLength":100},"replacement":{"type":"string","minLength":1,"maxLength":200}},"required":["word","replacement"]},"maxItems":500}},"required":["pronunciations"]}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object","properties":{"pronunciations":{"type":"array","items":{"$ref":"#/components/schemas/Pronunciation"}}},"required":["pronunciations"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/phone-agents":{"get":{"operationId":"listPhoneAgents","tags":["Settings"],"summary":"Phone agents with their conversation settings","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Phone agents.","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/PhoneAgent"}}},"required":["agents"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/phone-agents/{id}":{"get":{"operationId":"getPhoneAgent","tags":["Settings"],"summary":"One phone agent","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Agent id."}],"responses":{"200":{"description":"The agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneAgent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updatePhoneAgent","tags":["Settings"],"summary":"Change only the fields sent; applied to the live agent","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Agent id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneAgentPatch"}}}},"responses":{"200":{"description":"Updated agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneAgent"}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamFailed"}}}},"/chat-agents":{"get":{"operationId":"listChatAgents","tags":["Settings"],"summary":"Chat agents with their conversation and widget settings","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Chat agents.","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/ChatAgent"}}},"required":["agents"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/chat-agents/{id}":{"get":{"operationId":"getChatAgent","tags":["Settings"],"summary":"One chat agent","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Agent id."}],"responses":{"200":{"description":"The agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgent"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateChatAgent","tags":["Settings"],"summary":"Change only the fields sent; applied to the live agent","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Agent id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgentPatch"}}}},"responses":{"200":{"description":"Updated agent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatAgent"}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamFailed"}}}},"/integration":{"get":{"operationId":"getIntegration","tags":["Settings"],"summary":"The connected shop: status, last sync, switches","description":"Requires `account:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"account:read","security":[{"apiKey":[]},{"appToken":["account:read"]},{"mcpToken":["read"]}],"responses":{"200":{"description":"`integration` is null when no shop is connected.","content":{"application/json":{"schema":{"type":"object","properties":{"integration":{"anyOf":[{"$ref":"#/components/schemas/Integration"},{"type":"null"}]}},"required":["integration"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateIntegration","tags":["Settings"],"summary":"Pause/resume the shop connection and the sync switches","description":"Shop keys are changed in the dashboard only.\n\nRequires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused"]},"existing_products_stock_only":{"type":"boolean"},"sync_products":{"type":"boolean"},"sync_orders":{"type":"boolean"}},"minProperties":1}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"integration":{"$ref":"#/components/schemas/Integration"}},"required":["integration"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/integration/sync":{"post":{"operationId":"syncIntegration","tags":["Settings"],"summary":"Pull the whole catalogue and recent orders again, in the background","description":"Requires `settings:write`. API keys may call everything.","x-required-scope":"settings:write","security":[{"apiKey":[]},{"appToken":["settings:write"]},{"mcpToken":["settings:write"]}],"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"type":"object","properties":{"started":{"type":"boolean"},"reason":{"type":"string","description":"When `started` is false: a sync is already running."}},"required":["started"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`conflict` — the integration is paused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/team":{"get":{"operationId":"listTeam","tags":["Team"],"summary":"Who has access to this company","description":"Requires `team:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"team:read","security":[{"apiKey":[]},{"mcpToken":["read"]}],"responses":{"200":{"description":"Members.","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}}},"required":["members"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"inviteTeamMember","tags":["Team"],"summary":"Invite by email (owners only)","description":"Requires `team:write`. API keys may call everything.","x-required-scope":"team:write","security":[{"apiKey":[]},{"mcpToken":["team:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":200},"name":{"type":"string","minLength":2,"maxLength":120},"role":{"type":"string","description":"Default `vendor_member`.","enum":["vendor_owner","vendor_member"]}},"required":["email","name"]}}}},"responses":{"201":{"description":"Invited.","content":{"application/json":{"schema":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"`invited` (new login) or `added` (existing login).","enum":["invited","added"]},"message":{"type":"string"}},"required":["user_id","status","message"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/team/{user_id}":{"patch":{"operationId":"updateTeamMember","tags":["Team"],"summary":"Change a member's role (owners only; the last owner cannot be demoted)","description":"Requires `team:write`. API keys may call everything.","x-required-scope":"team:write","security":[{"apiKey":[]},{"mcpToken":["team:write"]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"User id."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["vendor_owner","vendor_member"]}},"required":["role"]}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","properties":{"updated":{"type":"boolean","const":true}},"required":["updated"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"removeTeamMember","tags":["Team"],"summary":"Remove a member from this company (owners only)","description":"Requires `team:write`. API keys may call everything.","x-required-scope":"team:write","security":[{"apiKey":[]},{"mcpToken":["team:write"]}],"parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"User id."}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","const":true}},"required":["removed"]}}}},"400":{"$ref":"#/components/responses/SettingsInvalid"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api-keys":{"get":{"operationId":"listApiKeys","tags":["Team"],"summary":"API keys of this company; only the prefix is visible","description":"Requires `team:write`. API keys may call everything.","x-required-scope":"team:write","security":[{"apiKey":[]},{"mcpToken":["team:write"]}],"responses":{"200":{"description":"Keys.","content":{"application/json":{"schema":{"type":"object","properties":{"api_keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}},"required":["api_keys"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"createApiKey","tags":["Team"],"summary":"Create an API key; the full key is returned once","description":"Requires `team:write`. API keys may call everything.","x-required-scope":"team:write","security":[{"apiKey":[]},{"mcpToken":["team:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Default \"API key\".","maxLength":80}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreated"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","tags":["Team"],"summary":"Revoke an API key; whatever uses it stops at once","description":"Requires `team:write`. API keys may call everything.","x-required-scope":"team:write","security":[{"apiKey":[]},{"mcpToken":["team:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"API key id."}],"responses":{"200":{"description":"Revoked.","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","const":true}},"required":["revoked"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/app":{"get":{"operationId":"getAppInstallation","tags":["App"],"summary":"This installation: company, version, scopes, readiness","description":"The first call an app makes after exchanging the install code.\n\nOnly for an app installation token (`hva_…`); other tokens get 403 `app_token_required`.","x-required-scope":null,"security":[{"appToken":[]}],"responses":{"200":{"description":"Installation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppInstallation"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/app/ready":{"post":{"operationId":"markAppReady","tags":["App"],"summary":"Switch the app's agent tools on","description":"Tools stay off until this is called. Calling it again does nothing.\n\nOnly for an app installation token (`hva_…`); other tokens get 403 `app_token_required`.","x-required-scope":null,"security":[{"appToken":[]}],"responses":{"200":{"description":"Ready.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"ready_at":{"type":"string","format":"date-time"}},"required":["ok","ready_at"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/app/events/test":{"post":{"operationId":"sendTestEvent","tags":["App"],"summary":"Send a sample event to this installation only","description":"The delivered `data` carries `test: true`. Without `data`, a built-in sample is sent.\n\nOnly for an app installation token (`hva_…`); other tokens get 403 `app_token_required`.","x-required-scope":null,"security":[{"appToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["order.created","order.status_changed","order.updated","conversation.ended","conversation.analyzed","callback.requested","appointment.booked","appointment.changed","product.updated","customer.redact","app.uninstalled"]},"data":{"type":"object","additionalProperties":true,"description":"Your own sample data."}},"required":["event"]}}}},"responses":{"200":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"event":{"type":"string","enum":["order.created","order.status_changed","order.updated","conversation.ended","conversation.analyzed","callback.requested","appointment.booked","appointment.changed","product.updated","customer.redact","app.uninstalled"]}},"required":["ok","event"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`not_subscribed` — the manifest does not list this event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/discounts":{"post":{"operationId":"createDiscount","tags":["Discounts"],"summary":"Attach a discount to the order the agent is about to place","description":"When the agent creates the order in that conversation, pending discounts are applied and the order total is reduced; the discount then moves to `applied` with `order_id`. Sent to the shop where supported (`GET /app` → `capabilities.order_discounts`). Unused discounts expire after 60 minutes.\n\nRequires `orders:write`. API keys may call everything.","x-required-scope":"orders:write","security":[{"apiKey":[]},{"appToken":["orders:write"]},{"mcpToken":["orders:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscountInput"}}}},"responses":{"201":{"description":"Pending discount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"`discounts_unsupported` (the shop does not accept them) or `too_many_discounts` (limit of pending ones in this conversation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/discounts/{id}":{"get":{"operationId":"getDiscount","tags":["Discounts"],"summary":"State of a discount","description":"Requires `orders:read` (MCP tokens: `read`). API keys may call everything.","x-required-scope":"orders:read","security":[{"apiKey":[]},{"appToken":["orders:read"]},{"mcpToken":["read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Discount id."}],"responses":{"200":{"description":"The discount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"operationId":"cancelDiscount","tags":["Discounts"],"summary":"Cancel a pending discount","description":"Requires `orders:write`. API keys may call everything.","x-required-scope":"orders:write","security":[{"apiKey":[]},{"appToken":["orders:write"]},{"mcpToken":["orders:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Discount id."}],"responses":{"200":{"description":"Cancelled (`status: cancelled`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"description":"`not_pending` — already applied, cancelled or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"webhooks":{"order.created":{"post":{"operationId":"event_order_created","tags":["Events"],"summary":"A new order — from the agent, the API or the shop","description":"Sent to the manifest's `webhooks.url`; needs `orders:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"orders:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"order.created"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventOrderCreated"}}}},"responses":{"2XX":{"description":"Received."}}}},"order.status_changed":{"post":{"operationId":"event_order_status_changed","tags":["Events"],"summary":"An order changed status","description":"Sent to the manifest's `webhooks.url`; needs `orders:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"orders:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"order.status_changed"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventOrderStatusChanged"}}}},"responses":{"2XX":{"description":"Received."}}}},"order.updated":{"post":{"operationId":"event_order_updated","tags":["Events"],"summary":"An order's address, items, name, phone or note changed","description":"Sent to the manifest's `webhooks.url`; needs `orders:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"orders:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"order.updated"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventOrderUpdated"}}}},"responses":{"2XX":{"description":"Received."}}}},"conversation.ended":{"post":{"operationId":"event_conversation_ended","tags":["Events"],"summary":"A call or chat ended","description":"Sent to the manifest's `webhooks.url`; needs `conversations:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"conversations:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.ended"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventConversationEnded"}}}},"responses":{"2XX":{"description":"Received."}}}},"conversation.analyzed":{"post":{"operationId":"event_conversation_analyzed","tags":["Events"],"summary":"The analysis of a conversation is ready","description":"Sent to the manifest's `webhooks.url`; needs `conversations:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"conversations:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"conversation.analyzed"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventConversationAnalyzed"}}}},"responses":{"2XX":{"description":"Received."}}}},"callback.requested":{"post":{"operationId":"event_callback_requested","tags":["Events"],"summary":"A customer asked to be called back","description":"Sent to the manifest's `webhooks.url`; needs `requests:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"requests:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"callback.requested"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCallbackRequested"}}}},"responses":{"2XX":{"description":"Received."}}}},"appointment.booked":{"post":{"operationId":"event_appointment_booked","tags":["Events"],"summary":"An appointment was booked","description":"Sent to the manifest's `webhooks.url`; needs `requests:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"requests:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"appointment.booked"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAppointmentBooked"}}}},"responses":{"2XX":{"description":"Received."}}}},"appointment.changed":{"post":{"operationId":"event_appointment_changed","tags":["Events"],"summary":"An appointment was confirmed, moved, finished or cancelled","description":"Sent to the manifest's `webhooks.url`; needs `requests:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"requests:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"appointment.changed"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAppointmentChanged"}}}},"responses":{"2XX":{"description":"Received."}}}},"product.updated":{"post":{"operationId":"event_product_updated","tags":["Events"],"summary":"Products or stock changed","description":"Sent to the manifest's `webhooks.url`; needs `catalog:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"catalog:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"product.updated"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventProductUpdated"}}}},"responses":{"2XX":{"description":"Received."}}}},"customer.redact":{"post":{"operationId":"event_customer_redact","tags":["Events"],"summary":"A customer asked to be deleted","description":"Sent to the manifest's `webhooks.url`; needs `customers:read`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":"customers:read","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"customer.redact"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCustomerRedact"}}}},"responses":{"2XX":{"description":"Received."}}}},"app.uninstalled":{"post":{"operationId":"event_app_uninstalled","tags":["Events"],"summary":"The app was uninstalled","description":"Sent to the manifest's `webhooks.url`. Respond 2xx within 10 s. Anything else is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h and 12 h; a subscription with no successful delivery for 24 hours is switched off. `id` is the same on every retry.","x-required-scope":null,"parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Event","in":"header","required":true,"schema":{"type":"string","const":"app.uninstalled"}},{"name":"HelpVox-Event-Id","in":"header","required":true,"schema":{"type":"string","pattern":"^evt_"}},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventAppUninstalled"}}}},"responses":{"2XX":{"description":"Received."}}}},"agentToolCall":{"post":{"operationId":"agentToolCall","tags":["Agent tools"],"summary":"HelpVox calls an app's agent tool during a conversation","description":"Sent to the tool's `url` from the manifest. Respond HTTP 200 with JSON. The timeout is `timeout_ms` (fast tools on the phone are capped at 1500 ms; `slow: true` tools wait up to 8000 ms). Timeouts, non-2xx and malformed bodies make the agent continue without the tool. The result is shown to the model as data — instructions inside it are ignored. The model sees the tool as `<slug with - → _>__<name>`.","x-required-scope":"agent:tools","parameters":[{"name":"HelpVox-Signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=\\d+,v1=[0-9a-f]{64}$"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256(client_secret, \"<t>.<raw body>\")>`. Verify against the raw body with a constant-time compare and reject when |now − t| > 300 s."},{"name":"HelpVox-Installation","in":"header","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentToolCall"}}}},"responses":{"200":{"description":"The tool's answer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentToolResult"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key `hv_live_…`. Company-wide; may call every endpoint regardless of scope."},"appToken":{"type":"http","scheme":"bearer","description":"App installation token `hva_…`. Scopes: `catalog:read`, `orders:read`, `customers:read`, `conversations:read`, `transcripts:read`, `requests:read`, `knowledge:read`, `account:read`, `orders:write`, `requests:write`, `knowledge:write`, `products:write`, `profile:write`, `settings:write`, `agent:tools`. Dies on uninstall or suspension."},"mcpToken":{"type":"http","scheme":"bearer","description":"MCP OAuth access token `hvo_…`. Scopes: `read` (every `*:read`), `orders:write`, `requests:write`, `knowledge:write`, `products:write`, `profile:write`, `settings:write`, `team:write`."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable, e.g. `unauthorized`, `insufficient_scope`, `not_found`, `validation_error`, `conflict`, `rate_limited`."},"message":{"type":"string","description":"For humans; may change."},"scope":{"type":"string","description":"With `insufficient_scope`: the scope the endpoint needs."},"details":{"type":"object","additionalProperties":true,"description":"With `validation_error`: zod's flattened issues (`formErrors`, `fieldErrors`)."}},"required":["code"],"additionalProperties":true}},"required":["error"]},"Meta":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}},"required":["total","limit","offset","has_more"]},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order_number":{"type":"string","description":"Short order number, e.g. \"1001\"."},"external_ref":{"type":["string","null"],"description":"Reference in the external system (shop, WMS, ERP)."},"source":{"type":"string","description":"Where the order came from, e.g. `agent`, `api`, or the connected shop."},"status":{"type":"string","description":"One of `new`, `processing`, `prepared`, `in_transit`, `delivery_failed`, `delivered`, `cancelled`, `returned`. Older integrations may still send `packed`, `shipped` and `return_requested`; they are stored as the new names."},"payment_status":{"type":["string","null"],"description":"`pending`, `collected` or `paid_out` — only when the vendor's own system sends it."},"customer_name":{"type":"string","description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"customer_phone":{"type":"string","description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_address":{"type":["string","null"],"description":"Full address as one line; empty for digital items. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_city":{"type":["string","null"],"description":"City. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_quarter":{"type":["string","null"],"description":"Quarter / district. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_street":{"type":["string","null"],"description":"Street. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_office":{"type":["string","null"],"description":"Courier office name, for office delivery. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_office_code":{"type":["string","null"],"description":"Courier office identifier from the courier's own list. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_post_code":{"type":["string","null"],"description":"Postal code. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_street_num":{"type":["string","null"],"description":"Street number. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_building":{"type":["string","null"],"description":"Building / block. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_entrance":{"type":["string","null"],"description":"Entrance. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_floor":{"type":["string","null"],"description":"Floor. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_apartment":{"type":["string","null"],"description":"Apartment. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"delivery_other":{"type":["string","null"],"description":"Landmark for the courier (\"first door on the left\"), not part of the address. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"address_meta":{"type":["object","null"],"additionalProperties":true,"description":"Courier nomenclature identifiers, returned as they were sent. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"tracking_number":{"type":["string","null"]},"courier":{"type":["string","null"]},"courier_service":{"type":["string","null"]},"subtotal_amount":{"type":["string","null"],"description":"Sum of the items.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"shipping_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"discount_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"vat_rate":{"type":["string","null"],"description":"In percent.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"vat_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"total_amount":{"type":"string","description":"What the courier collects: items − discount + shipping.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"cod_amount":{"type":["string","null"],"description":"Cash on delivery to collect; less than the total for partly paid orders.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"total_weight_kg":{"type":["string","null"],"format":"decimal","pattern":"^\\d+(\\.\\d+)?$"},"placed_at":{"type":["string","null"],"description":"When the order was really placed (imported orders are older than HelpVox).","format":"date-time"},"scheduled_at":{"type":["string","null"],"description":"Requested delivery day/time.","format":"date-time"},"currency":{"type":"string","description":"ISO 4217."},"created_at":{"type":"string","format":"date-time"},"channel":{"type":"string","description":"`phone` or `chat`."},"customer_email":{"type":["string","null"],"description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2."},"payment_method":{"type":["string","null"],"description":"`cash_on_delivery`, `card`, `prepaid`, or null when the source does not say."},"notes":{"type":["string","null"]},"cancel_reason":{"type":["string","null"]},"return_reason":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}}},"required":["id","order_number","external_ref","source","status","payment_status","tracking_number","courier","courier_service","subtotal_amount","shipping_amount","discount_amount","vat_rate","vat_amount","total_amount","cod_amount","total_weight_kg","placed_at","scheduled_at","currency","created_at","channel","country_code","payment_method","notes","cancel_reason","return_reason","updated_at","items"]},"OrderItem":{"type":"object","properties":{"product_id":{"type":["string","null"],"description":"Catalogue product, when the item's SKU matched one.","format":"uuid"},"variant_id":{"type":["string","null"],"description":"Catalogue variant, when the item's SKU matched one.","format":"uuid"},"sku":{"type":["string","null"]},"name":{"type":"string","description":"Product name as it was when the order was placed."},"variant":{"type":["string","null"],"description":"Variant label, e.g. \"Size 42, black\"."},"quantity":{"type":"integer","minimum":1},"unit_price":{"type":"string","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"discount_amount":{"type":["string","null"],"description":"Line discount, in money.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"vat_rate":{"type":["string","null"],"description":"VAT rate of this line, in percent.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"vat_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"total_amount":{"type":["string","null"],"description":"Line total.","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"currency":{"type":"string","description":"ISO 4217."}},"required":["product_id","variant_id","sku","name","variant","quantity","unit_price","discount_amount","vat_rate","vat_amount","total_amount"]},"CreateOrder":{"type":"object","properties":{"external_ref":{"type":"string","description":"Your reference. Sending the same one again returns the existing order (idempotent).","minLength":1,"maxLength":120},"customer_name":{"type":"string","minLength":2,"maxLength":200},"customer_phone":{"type":"string","minLength":5,"maxLength":32},"customer_email":{"type":"string","format":"email","maxLength":200},"delivery_address":{"type":"string","description":"Full address as one line.","minLength":5,"maxLength":400},"delivery_city":{"type":"string","description":"City.","maxLength":120},"delivery_quarter":{"type":"string","description":"Quarter / district.","maxLength":120},"delivery_street":{"type":"string","description":"Street.","maxLength":200},"delivery_office":{"type":"string","description":"Courier office name, for office delivery.","maxLength":160},"delivery_office_code":{"type":"string","description":"Courier office identifier from the courier's own list.","maxLength":60},"delivery_post_code":{"type":"string","description":"Postal code.","maxLength":20},"delivery_street_num":{"type":"string","description":"Street number.","maxLength":60},"delivery_building":{"type":"string","description":"Building / block.","maxLength":60},"delivery_entrance":{"type":"string","description":"Entrance.","maxLength":30},"delivery_floor":{"type":"string","description":"Floor.","maxLength":30},"delivery_apartment":{"type":"string","description":"Apartment.","maxLength":30},"delivery_other":{"type":"string","description":"Landmark for the courier (\"first door on the left\"), not part of the address.","maxLength":200},"address_meta":{"type":"object","additionalProperties":true,"description":"Courier nomenclature identifiers; stored and returned as sent."},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2, case-insensitive. Default BG.","minLength":2,"maxLength":2},"currency":{"type":"string","description":"ISO 4217, case-insensitive.","minLength":3,"maxLength":3},"payment_method":{"type":"string","description":"Default `cash_on_delivery`.","maxLength":60},"payment_status":{"type":"string","enum":["pending","collected","paid_out"]},"status":{"type":"string","description":"Default `new`. Legacy names are stored as the new ones.","enum":["new","processing","prepared","in_transit","delivery_failed","delivered","cancelled","returned","packed","shipped","return_requested"]},"tracking_number":{"type":"string","maxLength":80},"courier":{"type":"string","maxLength":60},"courier_service":{"type":"string","maxLength":60},"shipping_amount":{"type":"number","minimum":0},"discount_amount":{"type":"number","minimum":0},"vat_rate":{"type":"number","minimum":0,"maximum":100},"vat_amount":{"type":"number","minimum":0},"total_amount":{"type":"number","description":"Default: items + shipping − discount. When sent, it wins.","minimum":0},"cod_amount":{"type":"number","minimum":0},"total_weight_kg":{"type":"number","minimum":0,"maximum":10000},"placed_at":{"type":"string","description":"When the order was placed in your system.","format":"date-time"},"scheduled_at":{"type":"string","description":"Requested delivery day/time.","format":"date-time"},"notes":{"type":"string","maxLength":1000},"channel":{"type":"string","description":"`web` and `import` are stored as `chat`.","enum":["phone","chat","web","import"]},"items":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string","description":"Variant SKU. When it matches the catalogue, the item is linked to that variant.","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":512},"quantity":{"type":"integer","minimum":1,"maximum":500},"unit_price":{"type":"number","minimum":0},"discount_amount":{"type":"number","description":"Line discount in money (a percentage must be converted first).","minimum":0},"vat_rate":{"type":"number","description":"VAT rate of this line, in percent.","minimum":0,"maximum":100},"vat_amount":{"type":"number","minimum":0},"total_amount":{"type":"number","description":"Line total as your system computed it; default unit_price × quantity − discount_amount.","minimum":0}},"required":["name","quantity","unit_price"]},"minItems":1,"maxItems":100}},"required":["customer_name","customer_phone","delivery_address","currency","items"]},"OrderEventInput":{"type":"object","properties":{"occurred_at":{"type":"string","description":"ISO 8601, with or without an offset.","format":"date-time"},"description":{"type":"string","minLength":2,"maxLength":400},"location":{"type":"string","maxLength":200},"source":{"type":"string","description":"E.g. the courier's name.","maxLength":60}},"required":["occurred_at","description"]},"OrderEvent":{"type":"object","properties":{"occurred_at":{"type":"string","format":"date-time"},"description":{"type":"string"},"location":{"type":["string","null"]},"source":{"type":["string","null"]}},"required":["occurred_at","description","location","source"]},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string","description":"Your product identifier; the key for upserts."},"name":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"],"description":"Primary category path as text (legacy)."},"categories":{"type":"array","items":{"$ref":"#/components/schemas/ProductCategory"},"description":"All categories; `primary` marks the main one."},"brand":{"type":["string","null"]},"image_url":{"type":["string","null"],"description":"Main image. Present in `GET /products` only.","format":"uri"},"attributes":{"type":["object","null"],"additionalProperties":true},"active":{"type":"boolean","description":"False when switched off or when the product has no variants (no price)."},"updated_at":{"type":"string","format":"date-time"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}}},"required":["id","external_id","name","description","category","categories","brand","attributes","active","updated_at","variants"]},"ProductInput":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":128},"name":{"type":"string","minLength":1,"maxLength":512},"description":{"type":["string","null"],"maxLength":10000},"category":{"type":["string","null"],"description":"Primary category path, e.g. \"Audio / Headphones\". Missing levels are created.","maxLength":400},"categories":{"type":"array","items":{"type":"string","minLength":1,"maxLength":400},"description":"All category paths; the first is primary. Wins over `category`.","maxItems":20},"brand":{"type":["string","null"],"maxLength":256},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"attributes":{"type":"object","additionalProperties":true},"active":{"type":"boolean","default":true},"variants":{"type":"array","items":{"type":"object","properties":{"sku":{"type":["string","null"],"description":"Variant SKU.","minLength":1,"maxLength":128},"label":{"type":["string","null"],"maxLength":200},"attributes":{"type":["object","null"],"additionalProperties":true},"barcode":{"type":["string","null"],"maxLength":64},"image_url":{"type":["string","null"],"format":"uri","maxLength":500},"weight_kg":{"type":["number","null"],"minimum":0,"maximum":1000},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2, case-insensitive.","minLength":2,"maxLength":2},"price":{"type":"number","minimum":0},"currency":{"type":"string","description":"ISO 4217, case-insensitive.","minLength":3,"maxLength":3},"stock_quantity":{"type":["integer","null"],"minimum":0},"available":{"type":"boolean","default":true}},"required":["country_code","price","currency"],"description":"A sellable variant with its price in one market. The same variant sold in two countries is two rows with the same `sku`."},"description":"Required (or the deprecated `offers`): a product without variants cannot be sold.","minItems":1,"maxItems":200},"offers":{"type":"array","items":{"type":"object","properties":{"country_code":{"type":"string","description":"ISO 3166-1 alpha-2, case-insensitive.","minLength":2,"maxLength":2},"price":{"type":"number","minimum":0},"currency":{"type":"string","description":"ISO 4217, case-insensitive.","minLength":3,"maxLength":3},"stock_quantity":{"type":["integer","null"],"minimum":0},"available":{"type":"boolean","default":true}},"required":["country_code","price","currency"]},"description":"Deprecated — use `variants`. Each offer becomes a variant with the product's external_id as SKU.","minItems":1,"deprecated":true}},"required":["external_id","name"]},"ProductCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"path":{"type":"string"},"primary":{"type":"boolean"}},"required":["id","name","path","primary"]},"Variant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sku":{"type":"string"},"label":{"type":["string","null"],"description":"Human-readable, e.g. \"Size 42, black\"; falls back to the SKU."},"attributes":{"type":"object","additionalProperties":true,"description":"What sets the variant apart, e.g. {\"size\": \"42\", \"colour\": \"black\"}."},"barcode":{"type":["string","null"],"description":"EAN/GTIN."},"image_url":{"type":["string","null"],"format":"uri"},"weight_kg":{"type":["number","null"]},"country_code":{"type":"string","description":"Market this price applies to (ISO 3166-1 alpha-2)."},"price":{"type":"number"},"currency":{"type":"string","description":"ISO 4217."},"stock_quantity":{"type":["integer","null"],"description":"Null = not tracked."},"available":{"type":"boolean"}},"required":["id","sku","label","attributes","barcode","image_url","weight_kg","country_code","price","currency","stock_quantity","available"]},"UpsertResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["created","updated"]}},"required":["external_id","id","action"]}},"embedded":{"type":"integer","description":"How many products got new search embeddings."}},"required":["results","embedded"]},"Category":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"parent_id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string"},"path":{"type":"string","description":"Full path, e.g. \"Audio / Headphones\"."},"depth":{"type":"integer"},"sort_order":{"type":"integer"},"product_count":{"type":"integer","description":"Products directly in this category."},"product_count_with_subcategories":{"type":"integer"},"external_source":{"type":["string","null"],"description":"The shop the category was imported from."},"external_source_id":{"type":["string","null"]},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","parent_id","name","path","depth","sort_order","product_count","product_count_with_subcategories","external_source","external_source_id","updated_at"]},"Call":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string","description":"`phone` or `chat`."},"caller_number":{"type":["string","null"],"description":"E.164; null for web chat. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"language":{"type":["string","null"]},"status":{"type":"string","description":"`completed`, `failed` or `in_progress`."},"duration_seconds":{"type":["integer","null"]},"started_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"analysis":{"anyOf":[{"$ref":"#/components/schemas/CallAnalysisBrief"},{"type":"null"}]}},"required":["id","channel","language","status","duration_seconds","started_at","created_at","analysis"]},"CallDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"channel":{"type":"string","description":"`phone` or `chat`."},"caller_number":{"type":["string","null"],"description":"E.164; null for web chat. Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"language":{"type":["string","null"]},"status":{"type":"string","description":"`completed`, `failed` or `in_progress`."},"duration_seconds":{"type":["integer","null"]},"started_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"transcript":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptTurn"},"description":"Empty when there is no transcript. Personal data: removed from the response without `transcripts:read`.","x-personal-data":"transcripts:read"},"analysis":{"anyOf":[{"$ref":"#/components/schemas/CallAnalysis"},{"type":"null"}]}},"required":["id","channel","language","status","duration_seconds","started_at","created_at","analysis"]},"CallAnalysisBrief":{"type":"object","properties":{"purpose":{"type":["string","null"]},"topic":{"type":["string","null"]},"sentiment":{"type":["string","null"],"description":"`positive`, `neutral` or `negative`."},"follow_up_needed":{"type":"boolean"}},"required":["purpose","topic","sentiment","follow_up_needed"]},"CallAnalysis":{"type":"object","properties":{"purpose":{"type":["string","null"]},"topic":{"type":["string","null"]},"summary":{"type":["string","null"],"description":"Personal data: removed from the response without `transcripts:read`.","x-personal-data":"transcripts:read"},"resolution":{"type":["string","null"]},"sentiment":{"type":["string","null"],"description":"`positive`, `neutral` or `negative`."},"follow_up_needed":{"type":"boolean"},"products_mentioned":{"type":["array","null"],"items":{"type":"string"}}},"required":["purpose","topic","resolution","sentiment","follow_up_needed","products_mentioned"]},"TranscriptTurn":{"type":"object","properties":{"role":{"type":"string","enum":["agent","user"]},"message":{"type":"string"},"timeInCallSecs":{"type":"number","description":"Seconds from the start of the call (camelCase, as stored)."}},"required":["role","message"]},"Callback":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"caller_name":{"type":["string","null"],"description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"phone_number":{"type":"string","description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"reason":{"type":"string"},"country_code":{"type":["string","null"]},"status":{"type":"string","enum":["pending","done"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","reason","country_code","status","created_at"]},"Appointment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["requested","confirmed","cancelled","done"]},"channel":{"type":"string","description":"`phone` or `chat`."},"customer_name":{"type":"string","description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"customer_phone":{"type":"string","description":"Personal data: removed from the response without `customers:read`.","x-personal-data":"customers:read"},"service":{"type":"string","description":"What the customer asked for."},"preferred_time":{"type":"string","description":"As the customer said it, e.g. \"Friday after 2 pm\"."},"confirmed_for":{"type":["string","null"],"format":"date-time"},"notes":{"type":["string","null"]},"outcome":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}},"required":["id","status","channel","service","preferred_time","confirmed_for","notes","outcome","created_at"]},"KnowledgeItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"question":{"type":"string"},"answer":{"type":"string"}},"required":["id","question","answer"]},"KnowledgeInput":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string","minLength":3,"maxLength":1000},"answer":{"type":"string","minLength":1,"maxLength":5000}},"required":["question","answer"]},"minItems":1,"maxItems":500}},"required":["items"]},"Profile":{"type":"object","properties":{"company_name":{"type":"string"},"description":{"type":["string","null"]},"address":{"type":["string","null"]},"working_hours":{"type":["string","null"]},"delivery":{"type":["string","null"]},"returns":{"type":["string","null"]},"payment":{"type":["string","null"]},"contacts":{"type":["string","null"]},"promotions":{"type":["string","null"]},"digital_delivery":{"type":["string","null"]},"playbook":{"type":["string","null"]}},"required":["company_name","description","address","working_hours","delivery","returns","payment","contacts","promotions","digital_delivery","playbook"]},"GeneralSettings":{"type":"object","properties":{"name":{"type":"string","description":"Company name."},"base_country":{"type":"string"},"base_currency":{"type":"string"},"base_language":{"type":"string","description":"Dashboard language."},"test_mode":{"type":"boolean"},"plan":{"type":["string","null"],"description":"Null = no plan chosen."},"plan_status":{"type":["string","null"]}},"required":["name","base_country","base_currency","base_language","test_mode","plan","plan_status"]},"Market":{"type":"object","properties":{"country_code":{"type":"string"},"currency":{"type":"string"},"delivery_cost":{"type":["number","null"]},"free_delivery_over":{"type":["number","null"]},"delivery_days_min":{"type":["integer","null"]},"delivery_days_max":{"type":["integer","null"]},"courier":{"type":["string","null"]},"courier_service":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}},"required":["country_code","currency","delivery_cost","free_delivery_over","delivery_days_min","delivery_days_max","courier","courier_service","updated_at"]},"MarketInput":{"type":"object","properties":{"country_code":{"type":"string","minLength":2,"maxLength":2},"currency":{"type":["string","null"],"description":"Default: the country's currency.","minLength":3,"maxLength":3},"delivery_cost":{"type":["number","string","null"],"description":"Number or decimal string."},"free_delivery_over":{"type":["number","string","null"],"description":"Number or decimal string; must be > 0."},"delivery_days":{"type":["string","null"],"description":"\"2\" or \"1-3\".","maxLength":10},"courier":{"type":["string","null"],"maxLength":80},"courier_service":{"type":["string","null"],"maxLength":80}},"required":["country_code"]},"HoursBand":{"type":"object","properties":{"weekday":{"type":"integer","description":"0 = Monday … 6 = Sunday.","minimum":0,"maximum":6},"opens":{"type":"string","description":"HH:MM","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"closes":{"type":"string","description":"HH:MM, after `opens`.","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"}},"required":["weekday","opens","closes"]},"Resource":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","active","created_at"]},"TimeOff":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"starts_at":{"type":"string","format":"date-time"},"ends_at":{"type":"string","format":"date-time"},"reason":{"type":["string","null"]}},"required":["id","starts_at","ends_at","reason"]},"Pronunciation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"word":{"type":"string"},"replacement":{"type":"string"}},"required":["id","word","replacement"]},"PhoneAgent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["phone","chat"]},"name":{"type":["string","null"]},"country_code":{"type":["string","null"]},"language":{"type":"string"},"extra_languages":{"type":"array","items":{"type":"string"}},"greeting":{"type":["string","null"]},"voice_id":{"type":["string","null"]},"transfer_phone":{"type":["string","null"]},"llm":{"type":"string","description":"Empty = Standard."},"background_sound":{"type":"boolean"},"status":{"type":"string"},"provisioned":{"type":"boolean","description":"The live agent exists."},"phone_number":{"type":["string","null"]},"number_status":{"type":["string","null"]},"number_provider":{"type":["string","null"]}},"required":["id","kind","name","country_code","language","extra_languages","greeting","voice_id","transfer_phone","llm","background_sound","status","provisioned","phone_number","number_status","number_provider"]},"ChatAgent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["phone","chat"]},"name":{"type":["string","null"]},"country_code":{"type":["string","null"]},"language":{"type":"string"},"extra_languages":{"type":"array","items":{"type":"string"}},"greeting":{"type":["string","null"]},"voice_id":{"type":["string","null"]},"transfer_phone":{"type":["string","null"]},"llm":{"type":"string","description":"Empty = Standard."},"background_sound":{"type":"boolean"},"status":{"type":"string"},"provisioned":{"type":"boolean","description":"The live agent exists."},"widget_enabled":{"type":"boolean"},"theme":{"type":"string","enum":["light","dark"]},"accent":{"type":["string","null"],"description":"Hex colour; null = HelpVox violet."},"variant":{"type":"string","enum":["full","compact","tiny"]},"webmcp_enabled":{"type":"boolean"}},"required":["id","kind","name","country_code","language","extra_languages","greeting","voice_id","transfer_phone","llm","background_sound","status","provisioned","widget_enabled","theme","accent","variant","webmcp_enabled"]},"PhoneAgentPatch":{"type":"object","properties":{"language":{"type":"string","description":"Main language, e.g. bg, ro, en.","minLength":2,"maxLength":5},"extra_languages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":5},"description":"Languages the agent switches to if the customer speaks them.","maxItems":10},"greeting":{"type":["string","null"],"description":"Welcome message; null or empty = the standard greeting for the language.","maxLength":500},"voice_id":{"type":["string","null"],"description":"ElevenLabs voice id; null = default voice.","maxLength":64},"transfer_phone":{"type":["string","null"],"description":"E.164 number to transfer to during working hours (Growth and up); null = callbacks only.","maxLength":20},"llm":{"type":["string","null"],"description":"Thinking model id from the dashboard list; empty = Standard.","maxLength":40},"background_sound":{"type":"boolean","description":"Quiet office in the background."}}},"ChatAgentPatch":{"type":"object","properties":{"language":{"type":"string","description":"Main language, e.g. bg, ro, en.","minLength":2,"maxLength":5},"extra_languages":{"type":"array","items":{"type":"string","minLength":2,"maxLength":5},"description":"Languages the agent switches to if the customer speaks them.","maxItems":10},"greeting":{"type":["string","null"],"description":"Welcome message; null or empty = the standard greeting for the language.","maxLength":500},"voice_id":{"type":["string","null"],"description":"ElevenLabs voice id; null = default voice.","maxLength":64},"transfer_phone":{"type":["string","null"],"description":"E.164 number to transfer to during working hours (Growth and up); null = callbacks only.","maxLength":20},"llm":{"type":["string","null"],"description":"Thinking model id from the dashboard list; empty = Standard.","maxLength":40},"background_sound":{"type":"boolean","description":"Quiet office in the background."},"country_code":{"type":"string","description":"Market this widget sells in.","minLength":2,"maxLength":2},"widget_enabled":{"type":"boolean","description":"Visible to visitors."},"theme":{"type":"string","enum":["light","dark"]},"accent":{"type":["string","null"],"description":"Hex colour; null = HelpVox violet.","maxLength":16},"variant":{"type":"string","description":"Button size.","enum":["full","compact","tiny"]},"webmcp_enabled":{"type":"boolean","description":"Readable by assistants (WebMCP + UCP)."}}},"Integration":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"adapter":{"type":"string","description":"Shop platform, e.g. `woocommerce`, `shopify`."},"status":{"type":"string","description":"`active` or `paused`."},"base_url":{"type":["string","null"]},"country_code":{"type":["string","null"]},"currency":{"type":["string","null"]},"existing_products_stock_only":{"type":"boolean"},"sync_products":{"type":"boolean"},"sync_orders":{"type":"boolean"},"initial_sync_at":{"type":["string","null"],"format":"date-time"},"syncing_since":{"type":["string","null"],"description":"Set while a sync is running.","format":"date-time"},"sync_progress":{"type":["object","null"],"description":"Progress of the running sync (camelCase keys, as stored).","properties":{"phase":{"type":"string"},"productsSeen":{"type":"integer"},"productsImported":{"type":"integer"},"ordersSeen":{"type":"integer"},"ordersImported":{"type":"integer"},"page":{"type":"integer"},"lastPage":{"type":["integer","null"]}}},"last_sync_at":{"type":["string","null"],"format":"date-time"},"last_sync_status":{"type":["string","null"]},"last_sync_note":{"type":["string","null"]},"webhook_configured":{"type":"boolean"}},"required":["id","adapter","status","base_url","country_code","currency","existing_products_stock_only","sync_products","sync_orders","initial_sync_at","syncing_since","sync_progress","last_sync_at","last_sync_status","last_sync_note","webhook_configured"]},"TeamMember":{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","enum":["vendor_owner","vendor_member"]},"email_verified":{"type":"boolean"},"joined_at":{"type":"string","format":"date-time"}},"required":["user_id","name","email","role","email_verified","joined_at"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string","description":"First 12 characters of the key."},"last_used_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"}},"required":["id","name","prefix","last_used_at","created_at","revoked_at"]},"ApiKeyCreated":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"prefix":{"type":"string"},"key":{"type":"string","description":"The full key (`hv_live_…`). Shown only once.","pattern":"^hv_live_"},"created_at":{"type":"string","format":"date-time"}},"required":["id","name","prefix","key","created_at"]},"Me":{"type":"object","properties":{"vendor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"plan":{"type":["string","null"],"description":"Null = no plan chosen."},"plan_status":{"type":["string","null"]},"elevenlabs_key_configured":{"type":"boolean"}},"required":["id","name","slug","status","plan","plan_status","elevenlabs_key_configured"]},"usage":{"type":["object","null"],"description":"Null when usage could not be computed.","properties":{"credits_used":{"type":"number"},"credits_included":{"type":["number","null"]},"credits_left":{"type":["number","null"]},"minutes_used":{"type":"number","description":"Phone only; kept for older integrations — plans are measured in credits."},"minutes_included":{"type":["number","null"]}},"required":["credits_used","credits_included","credits_left","minutes_used","minutes_included"]},"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"country_code":{"type":["string","null"]},"phone_number":{"type":"string"},"language":{"type":"string"},"status":{"type":"string"},"agent_id":{"type":"string","format":"uuid"},"agent_provisioned":{"type":"boolean"}},"required":["id","country_code","phone_number","language","status","agent_id","agent_provisioned"]}},"chat_agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"language":{"type":"string"},"agent_provisioned":{"type":"boolean"}},"required":["id","language","agent_provisioned"]}},"product_count":{"type":"integer"}},"required":["vendor","usage","numbers","chat_agents","product_count"]},"AppInstallation":{"type":"object","properties":{"installation_id":{"type":"string","format":"uuid"},"app":{"type":"object","properties":{"slug":{"type":"string"},"version":{"type":"integer","description":"Version number of the installed manifest."}},"required":["slug","version"]},"vendor":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."},"currency":{"type":["string","null"],"description":"ISO 4217."},"language":{"type":["string","null"]}},"required":["id","name","country","currency","language"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Granted scopes."},"ready":{"type":"boolean","description":"`POST /app/ready` has been called; tools are live."},"update_pending":{"type":"boolean","description":"A newer version needs the merchant's approval."},"tools":{"type":"array","items":{"type":"string"},"description":"Names of the app's agent tools."},"events":{"type":"array","items":{"type":"string","enum":["order.created","order.status_changed","order.updated","conversation.ended","conversation.analyzed","callback.requested","appointment.booked","appointment.changed","product.updated","customer.redact","app.uninstalled"]},"description":"Subscribed events."},"capabilities":{"type":"object","properties":{"order_discounts":{"type":"boolean","description":"The company's shop accepts discounts from apps (`POST /discounts`)."}},"required":["order_discounts"]}},"required":["installation_id","app","vendor","scopes","ready","update_pending","tools","events","capabilities"]},"Discount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string"},"amount":{"type":"string","format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"currency":{"type":"string","description":"ISO 4217."},"label":{"type":"string"},"reference":{"type":["string","null"],"description":"Your own id for this discount."},"status":{"type":"string","description":"`pending` until the agent places the order in that conversation, then `applied`. A pending discount past `expires_at` reads as `expired`; `DELETE` makes it `cancelled`.","enum":["pending","applied","cancelled","expired"]},"order_id":{"type":["string","null"],"description":"Set once `applied`.","format":"uuid"},"expires_at":{"type":"string","format":"date-time"},"applied_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}},"required":["id","conversation_id","amount","currency","label","reference","status","order_id","expires_at","applied_at","created_at"]},"DiscountInput":{"type":"object","properties":{"conversation_id":{"type":"string","description":"The conversation the agent is placing the order in (`context.conversation_id` of a tool call).","minLength":3,"maxLength":200},"amount":{"type":"number","exclusiveMinimum":0,"maximum":100000},"currency":{"type":"string","description":"ISO 4217.","minLength":3,"maxLength":3},"label":{"type":"string","description":"Shown on the order, e.g. \"Loyalty points\".","minLength":1,"maxLength":80},"reference":{"type":"string","description":"Your own id for this discount.","maxLength":100}},"required":["conversation_id","amount","currency","label"]},"EventEnvelope":{"type":"object","properties":{"id":{"type":"string","description":"`evt_…`. The same for every retry — use it to deduplicate.","pattern":"^evt_"},"type":{"type":"string","enum":["order.created","order.status_changed","order.updated","conversation.ended","conversation.analyzed","callback.requested","appointment.booked","appointment.changed","product.updated","customer.redact","app.uninstalled"]},"created_at":{"type":"string","format":"date-time"},"vendor_id":{"type":"string","format":"uuid"},"installation_id":{"type":"string","format":"uuid"},"data":{"type":"object","additionalProperties":true,"description":"Event-specific. Test events from `POST /app/events/test` carry `test: true`."}},"required":["id","type","created_at","vendor_id","installation_id","data"]},"AgentToolCall":{"type":"object","properties":{"tool":{"type":"string","description":"Tool name from the manifest."},"input":{"type":"object","additionalProperties":true,"description":"Arguments, validated against the tool's `input_schema`."},"context":{"type":"object","properties":{"installation_id":{"type":"string","format":"uuid"},"vendor_id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["phone","chat","test"]},"conversation_id":{"type":["string","null"]},"language":{"type":["string","null"]},"country":{"type":["string","null"]},"caller_phone":{"type":["string","null"],"description":"Only with `customers:read`, on the phone channel, when known."}},"required":["installation_id","vendor_id","channel","conversation_id","language","country"]}},"required":["tool","input","context"]},"AgentToolResult":{"oneOf":[{"type":"object","properties":{"result":{"type":"string","description":"Plain text the agent relays.","maxLength":2000}},"required":["result"],"title":"Success"},{"type":"object","properties":{"error":{"type":"string","description":"Short reason the agent can tell the customer."}},"required":["error"],"title":"ExpectedFailure"}]},"EventOrderCreatedData":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":["string","null"]},"external_ref":{"type":["string","null"]},"status":{"type":["string","null"]},"source":{"type":["string","null"]},"channel":{"type":["string","null"]},"total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"currency":{"type":["string","null"]}},"required":["order_id","order_number","external_ref","status","source","channel","total_amount","currency"]},"EventOrderCreated":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"order.created"},"data":{"$ref":"#/components/schemas/EventOrderCreatedData"}},"required":["type","data"]}]},"EventOrderStatusChangedData":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":["string","null"]},"external_ref":{"type":["string","null"]},"status":{"type":["string","null"]},"source":{"type":["string","null"]},"channel":{"type":["string","null"]},"total_amount":{"type":["string","null"],"format":"decimal","pattern":"^-?\\d+(\\.\\d+)?$","examples":["49.90"]},"currency":{"type":["string","null"]},"previous_status":{"type":["string","null"]}},"required":["order_id","order_number","external_ref","status","source","channel","total_amount","currency","previous_status"]},"EventOrderStatusChanged":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"order.status_changed"},"data":{"$ref":"#/components/schemas/EventOrderStatusChangedData"}},"required":["type","data"]}]},"EventOrderUpdatedData":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":["string","null"]},"changed":{"type":"array","items":{"type":"string","enum":["address","name","phone","note","items"]}}},"required":["order_id","order_number","changed"]},"EventOrderUpdated":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"order.updated"},"data":{"$ref":"#/components/schemas/EventOrderUpdatedData"}},"required":["type","data"]}]},"EventConversationEndedData":{"type":"object","properties":{"call_id":{"type":"string","format":"uuid"},"conversation_id":{"type":["string","null"]},"channel":{"type":["string","null"]},"duration_seconds":{"type":["integer","null"]}},"required":["call_id","conversation_id","channel","duration_seconds"]},"EventConversationEnded":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"conversation.ended"},"data":{"$ref":"#/components/schemas/EventConversationEndedData"}},"required":["type","data"]}]},"EventConversationAnalyzedData":{"type":"object","properties":{"call_id":{"type":"string","format":"uuid"},"purpose":{"type":["string","null"]},"sentiment":{"type":["string","null"]},"follow_up_needed":{"type":["boolean","null"]}},"required":["call_id","purpose","sentiment","follow_up_needed"]},"EventConversationAnalyzed":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"conversation.analyzed"},"data":{"$ref":"#/components/schemas/EventConversationAnalyzedData"}},"required":["type","data"]}]},"EventCallbackRequestedData":{"type":"object","properties":{"callback_id":{"type":"string","format":"uuid"}},"required":["callback_id"]},"EventCallbackRequested":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"callback.requested"},"data":{"$ref":"#/components/schemas/EventCallbackRequestedData"}},"required":["type","data"]}]},"EventAppointmentBookedData":{"type":"object","properties":{"appointment_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["appointment_id","status"]},"EventAppointmentBooked":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"appointment.booked"},"data":{"$ref":"#/components/schemas/EventAppointmentBookedData"}},"required":["type","data"]}]},"EventAppointmentChangedData":{"type":"object","properties":{"appointment_id":{"type":"string","format":"uuid"},"status":{"type":"string"}},"required":["appointment_id","status"]},"EventAppointmentChanged":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"appointment.changed"},"data":{"$ref":"#/components/schemas/EventAppointmentChangedData"}},"required":["type","data"]}]},"EventProductUpdatedData":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":200}},"required":["product_ids"]},"EventProductUpdated":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"product.updated"},"data":{"$ref":"#/components/schemas/EventProductUpdatedData"}},"required":["type","data"]}]},"EventCustomerRedactData":{"type":"object","properties":{"phone":{"type":["string","null"]},"email":{"type":["string","null"]}},"required":["phone","email"],"description":"Delete what you hold about this customer. At least one of the two is set."},"EventCustomerRedact":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"customer.redact"},"data":{"$ref":"#/components/schemas/EventCustomerRedactData"}},"required":["type","data"]}]},"EventAppUninstalledData":{"type":"object","properties":{"installation_id":{"type":"string","format":"uuid"}},"required":["installation_id"],"description":"Delete or archive this company's data."},"EventAppUninstalled":{"allOf":[{"$ref":"#/components/schemas/EventEnvelope"},{"type":"object","properties":{"type":{"type":"string","const":"app.uninstalled"},"data":{"$ref":"#/components/schemas/EventAppUninstalledData"}},"required":["type","data"]}]}},"responses":{"BadRequest":{"description":"`invalid_request` — the body is missing or contradicts the rules (see `message`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"`unauthorized` — missing, malformed, revoked or expired token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"`insufficient_scope` (with `scope`) when the token lacks the endpoint's scope; `vendor_suspended` for a suspended account; `app_token_required` on app-only endpoints; `forbidden` when an owner-only action is attempted by a member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"`not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Conflict":{"description":"`conflict` or a more specific code (see the operation).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"`validation_error` — `details` has zod's flattened issues.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SettingsInvalid":{"description":"`validation_error` with status 400 — the value was well-formed but not acceptable (see `message`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamFailed":{"description":"`upstream_failed` — saved, but applying it to the live agent failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"`rate_limited` — 1000 requests per minute per token and endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"retry-after":{"schema":{"type":"integer"},"description":"Seconds to wait."}}}}}}