Tools, SDK and errors
Find Support tools, REST routes, permission levels, and common errors.
Use the support_* MCP tools, authenticated REST routes under /support, or the generated support namespace in @lepsto/sdk-app to manage Support. They expose the operations listed below with shared input and output schemas.
The tools
Operations cover conversations and their dictionaries, attachments, webhooks, surveys, responses, and delivery rules. All tools are product-scoped. Over MCP, each call names its product in a required product_id argument, which an API key may omit to use its own product. Over REST, the credential selects the product.
Read operations require read access and ordinary changes require write, with these admin exceptions: status archiving, deleting any message, reading message revisions, survey publication/unpublication/archiving, rule deletion, and every webhook operation, including reads. MCP tokens must grant the required operations.
Every REST path below is documented field by field on the Support API reference, and every tool has its own page under MCP tools.
The support model
Tool | REST | What it does |
|---|---|---|
GET /support/statuses | List statuses; seed defaults on first read | |
POST /support/statuses | Add a status | |
GET /support/statuses/{id} | Read a status, including archived ones | |
PATCH /support/statuses/{id} | Edit display fields; change category only while unused | |
POST /support/statuses/{id}/archive | Retire a status, moving its threads to a target | |
POST /support/agents | Create an agent profile | |
GET /support/agents | List agent profiles | |
GET /support/agents/{id} | Read a profile, including inactive ones | |
PATCH /support/agents/{id} | Edit, deactivate, or reactivate a profile | |
POST /support/labels | Add a label | |
GET /support/labels | List labels | |
GET /support/labels/{id} | Read a label by id | |
POST /support/threads | Open a thread on behalf of an end user | |
GET /support/threads | List and filter threads | |
GET /support/threads/{id} | Read a thread with its status | |
PATCH /support/threads/{id} | Edit title, priority, labels, and metadata | |
POST /support/threads/{id}/status | Move a thread to a status | |
POST /support/threads/{id}/assignment | Set or clear the assignee | |
POST /support/messages | Post a message into a thread | |
GET /support/messages | Read thread or product-wide messages | |
GET /support/messages/{id} | Read a message and its attachments | |
PATCH /support/messages/{id} | Edit the body of your own message (write) | |
DELETE /support/messages/{id} | Soft-delete your own message (write) | |
POST /support/messages/{id}/delete-any | Soft-delete any message of the product (admin) | |
GET /support/messages/{id}/revisions | Read message revisions (admin) | |
POST /support/attachments | Reserve a file and get an upload URL | |
POST /support/attachments/finalize | Verify and confirm an uploaded file | |
DELETE /support/attachments/{id} | Delete a file no message carries (write) | |
POST /support/attachments/purge | Delete every file of a thread that no message carries (write) |
Webhooks
Tool | REST | What it does |
|---|---|---|
POST /support/webhooks | Register an endpoint; return its secret once | |
GET /support/webhooks | List endpoints without secrets | |
GET /support/webhooks/{id} | Read an endpoint | |
PATCH /support/webhooks/{id} | Edit URL, events, description, or active/disabled state | |
DELETE /support/webhooks/{id} | Remove an endpoint and its delivery history | |
POST /support/webhooks/{id}/rotate-secret | Replace the signing secret and return the new one once | |
GET /support/webhook-deliveries | List and filter deliveries | |
POST /support/webhook-deliveries/redeliver | Send a past delivery again, with its original key |
For ownership rules and deleted-message rendering, see Correct or remove a message.
For payloads, signatures, and retries, see Receive Support events.
Surveys and responses
Tool | REST | What it does |
|---|---|---|
POST /support/surveys | Draft a survey with its question set | |
GET /support/surveys | List surveys | |
GET /support/surveys/{id} | Read a survey in any state | |
PATCH /support/surveys/{id} | Edit a draft, including its questions | |
POST /support/surveys/{id}/publish | Open it for answers, freezing the structure | |
POST /support/surveys/{id}/unpublish | Return it to draft and stop accepting responses | |
POST /support/surveys/{id}/archive | Retire a survey for good | |
GET /support/surveys/{id}/stats | Read response statistics, including NPS | |
GET /support/responses | List and filter responses for a survey | |
GET /support/responses/{id} | Read a response | |
POST /support/responses/{id}/escalate | Turn one response into a feedback thread |
Response submission is available only as public POST /surveys/{surveyId}/responses; it has no MCP tool. Your backend submits the person’s answers using a product public key. Requests carrying a Lepsto identity are rejected with public_edge_only. See Surveys and delivery rules for the response contract.
Delivery rules
Tool | REST | What it does |
|---|---|---|
POST /support/rules | Write a rule: where a survey is shown, on which devices, when and how often | |
GET /support/rules/{id} | Read a rule and its configuration | |
GET /support/rules | List rules newest first; filter by survey, state, URL, or device | |
PATCH /support/rules/{id} | Edit or disable a rule; its survey cannot change | |
DELETE /support/rules/{id} | Permanently delete a rule |
Support stores rule configuration and matches URLs and devices. Your runtime handles visitor checks, triggers, and frequency. See Delivery rules.
These tools are the authenticated management API used by agents and the Workspace app.
The generated SDK namespace
@lepsto/sdk-app generates a support namespace from the published operation catalog, using the same input and output schemas as the tools. Update the SDK to pick up newly published operations. There is no separate hand-written Support SDK package.
The public perimeter is a narrow subset
The tools, authenticated REST routes, and generated SDK require a platform identity. They do not accept a product public key.
The Public HTTP API provides sixteen routes at https://public.lepsto.com/{productId}/support for your backend, authenticated with a product public key. They open and read threads, post and read messages, read statuses, labels, and agents, reserve, confirm, and delete files, read published surveys, submit responses, and read matching delivery rules.
Public attachment reservation and confirmation are available from Support 0.10.0, and attachment deletion from Support 0.21.0.
Fifteen public routes also expose operations available through MCP. The exception is response submission, POST /surveys/{surveyId}/responses, which is public-only.
Public keys cannot assign threads, change statuses, create or edit agent profiles, edit or delete messages, or manage webhooks. Those paths return 404 on the public API. Agent-authored public-API messages must use an unbound bot or backend profile; profiles bound to Lepsto identities use the authenticated API.
Keep the public key on your backend. Your customer-facing support screen calls your backend, which authenticates the customer and calls Support.
Who is calling
Support authenticates your team, backend, or authorized agent as the caller. The external customers named in threads are not authenticated by Support.
The caller’s credentials establish the product boundary. Passing another product’s record id does not grant access to it.
Errors
Code | Means |
|---|---|
400 | The input is invalid, or the operation is refused: an archived status as a destination, a deactivated agent as an assignee, an attachment that is not claimable, cursor and offset together, an empty body on a message with no uploaded attachment |
401 | The call carries no usable identity |
403 | Editing or deleting — without admin — a message your identity did not create |
404 | The record does not exist or belongs to another product |
409 | A uniqueness or history conflict: a duplicate status, label or Lepsto binding, changing the category of a status in use, editing a deleted message, or deleting an attachment a message carries ( attachment_claimed:) |
503 | Storage could not remove attachment files ( attachment_cleanup_failed:) — on a message delete, an attachment delete, or an attachment purge. Repeat the call; it is safe |
Read validation errors for the failing fields. For operation refusals, follow the stated condition: for example, to recategorize threads on a status in use, create a status in the target category and move the threads to it.
Successful calls return the value described by the output schema. Error bodies depend on where a request failed; the public API has three documented error shapes. Do not assume every error has a code and message.
Not found, never forbidden
Records outside the call’s product return not found, without disclosing their existence or owner.
The same result covers nonexistent ids and records belonging to another customer.
This also applies to nested references: another product’s agent as a message author, label on a thread, or attachment in a message all return not found.
Where to go next
- Lepsto Support: the overview and the model behind these operations.
- Answer your first thread: a first thread, end to end.
- Public HTTP API: the sixteen keyed routes a client backend calls.