Get a message
const url = 'https://api.asklucy.eu/v1/conversations/example/messages/example';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.asklucy.eu/v1/conversations/example/messages/example \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”OK
object
For user messages, the local files and folders the person mentioned (@).
A file or folder on the conversation’s device that the person mentioned (@).
object
<share>/<path>, or the share itself; no empty, . or .. parts.
For an answer still being written, what’s been written so far.
object
Markdown. Lucy links the conversation’s files as [name](lucy://file/<file_id>) and published pages or live previews as [title](lucy://artifact/<preview_id>) (Preview.id, on a step of the conversation): open them in the viewer. Treat an ID that isn’t in the conversation as plain text; http(s) links are ordinary links.
object
A file of the same conversation.
The file has been deleted since.
Steps that ran at this point of the answer, between the text before and after, in the order they started: IDs of the message’s steps. Every step of an answer is in exactly one steps part. While it streams, a step.started after text opens a new group, and the next message.delta after a step opens a new text part.
object
User messages are always completed.
What Lucy did while writing this answer (assistant messages only).
Something visible Lucy did while answering, like running code.
object
ui (experimental): UI Lucy drew in its answer, in ui; the chat draws it where the step is, between the text before and after it, rather than as a step.
Short human label, e.g. “Analysing sales.xlsx” or “Following: Answer a custody-fee question (v3)”.
For code steps, what was run.
awaiting_approval: the step waits for the person. With
approval set, on that card in the chat (a tool set to ask);
a local step without one, on their computer. denied: they
said no or didn’t answer.
The end of the output (stdout and stderr), cut to a few KB.
What Lucy wants to do and is waiting for the person’s yes on (a Step with status awaiting_approval): a
call of a tool whose permission is ask for them. Answer it with decideApproval. The lines are what the
call does, from its exact arguments (long text is cut for the card; the approval covers the whole of it).
object
The tool server that receives the call. Absent on cards from before tool permissions.
object
For a connector added by URL, the host that receives the call’s arguments.
The call uses the organization’s shared account at that service.
The tool’s name on its server. Absent on cards from before tool permissions.
The answers to offer, in this order. approve_always only when the organization allows the tool
(organization is allow). Absent on cards from before tool permissions: approve and deny.
object
The model’s own reason for this step, in a few sentences (an excerpt of its reasoning, at most 600 characters), set on the first step of a round when the model reasoned before calling tools. Absent for models that don’t reason. It is part of the message, so it is kept and deleted with the conversation. Shown in the conversation’s Record; a record of the model’s working, not proof of why it acted.
object
found_processes,read_process: Lucy looked for a process that fits, or read one to follow it.searched,recalled: Lucy looked facts up (by search, or around an entity).remembered: Lucy kept facts or relations in your memory.saved_process: Lucy wrote or changed a process in your own scope;proposed_process: she proposed one for a group or the organization (an admin reviews it).forgot,shared: Lucy forgot something, or shared it (after you said yes).
What the step touched, to show and link to.
object
The fact’s text, the entity’s name, the relation in words, or the process’s title.
Who a piece of memory is for: user (only you, and Lucy when she
works for you), group:<groupId> (the members of a group from the
identity provider) or org (everyone in the organization).
For process_version.
For process_version.
The step wrote to your own memory and can be undone: forget its
fact and relation items (deleteMemoryFact,
deleteMemoryRelation) and withdraw its process_version
items (withdrawProcessVersion). Entities stay.
object
The shell comes with a later phase.
The shared folder, by its name.
The path inside the shares, <share>/<path> (for move, where from).
object
The change’s ID on the device (chg_…), for undoLocalChange.
When the person undid it.
For move, where to.
The file’s size after the change (for delete, before).
For edit and overwrite of text, a unified diff (at most 16,000 characters).
For edit and overwrite, the previous version’s name in the Trash.
Things to open from the step: a live preview of an app running in
Lucy’s sandbox, or a page she published. The links carry their own
access token and expire (expires_at): show them in a sandboxed
frame or a new tab, never trust their content, and say so when one
has expired.
object
Stable ID of the preview, which the answer links as lucy://artifact/<id>. Absent on previews made before 2026-11-03.
live: a web app running in the sandbox (works while the sandbox
and its server run, minutes to hours). artifact: a frozen static
page that outlives the sandbox (link valid for days).
An https link to open. Contains an access token.
The weather in one place, from a web search. Temperatures are in degrees Celsius; the chat converts them to the units the person uses.
object
object
It is dark there now.
Today in that place first, then the days after, in order.
object
Chance of rain or snow in percent, when the sources give one.
object
A2UI v0.9 server-to-client messages (a2ui.org) a tool gave for this step, or Lucy drew (kind ui): a surface, its components from Lucy’s catalog (https://asklucy.eu/a2ui/catalogs/lucy/v1.json) and their data. The chat draws them with its own components; nothing in them runs. Absent when the tool gave none. Experimental.
object
When the answer finished (any final status).
For an answer still being written: the last event already
included in this snapshot. Open the events stream with this as
Last-Event-ID to continue live from here (after a refresh, or
on another device).
object
no_vision: the turn had an image (or a tool showed one) and the
model can’t read images. no_tools: it needed tools the model
can’t use. too_long: the conversation is longer than its
context. unavailable: the model didn’t answer (Lucy used a
stand-in) or is no longer offered by Lucy. not_allowed: you may
no longer choose it, so Lucy chose (and model is null).
object
For people, e.g. “Codestral can’t read images.”
Example
{ "local_refs": [ { "share": "Contracts", "path": "Contracts/2024/acme.pdf", "kind": "file" } ], "id": "msg_9Qa1Zt", "role": "user", "content": [ { "type": "text" } ], "status": "completed", "steps": [ { "kind": "code", "status": "running", "connector": { "action": "search" }, "approval": { "id": "apr_8Qk2LmN4Rt7Wx1Yz3Aa5", "title": "Send an email", "server": { "id": "m365", "name": "Microsoft 365", "host": "mcp.acme.example" }, "tool": "mail_send", "choices": [ "approve" ], "lines": [ { "label": "To", "value": "harry@example.test" } ] }, "memory": { "action": "found_processes", "items": [ { "type": "fact", "id": "prv_7Hc2Lw", "scope": "user" } ] }, "local": { "device_name": "Thibaut's MacBook", "tool": "list", "share": "Contracts", "path": "Contracts/2024/acme.pdf", "change": { "id": "chg_4kVt9sQm2Lp8Xw0RbN3e", "operation": "create", "path": "Reports/q3.md" } }, "previews": [ { "id": "prv_8Hq2xT", "kind": "live" } ], "weather": { "place": "Las Vegas, NV", "current": { "condition": "clear", "summary": "Sunny" }, "days": [ { "condition": "clear" } ] }, "ui": [ { "version": "v0.9" } ] } ], "error": { "code": "sandbox_timeout" }, "feedback": { "rating": "positive" }, "created_by": { "kind": "person" }, "model_fallback": { "reason": "no_vision" }}Missing, expired or invalid token.
RFC 9457 problem details.
object
For quota-exceeded, the window that is used up.
object
Null for a rolling window that hasn’t started.
organization when the organization’s budget is closer to running out than the member’s own limit.
Field-level problems (400 only).
object
JSON pointer into the request body.
Example
{ "type": "https://docs.asklucy.eu/errors/answer-in-progress", "quota": { "window": "five_hours", "limited_by": "personal", "request": { "status": "pending" } }}Headers
Section titled “Headers”Unique per request; quote it to support.
No such object in your organization.
RFC 9457 problem details.
object
For quota-exceeded, the window that is used up.
object
Null for a rolling window that hasn’t started.
organization when the organization’s budget is closer to running out than the member’s own limit.
Field-level problems (400 only).
object
JSON pointer into the request body.
Example
{ "type": "https://docs.asklucy.eu/errors/answer-in-progress", "quota": { "window": "five_hours", "limited_by": "personal", "request": { "status": "pending" } }}Headers
Section titled “Headers”Unique per request; quote it to support.