Post in a thread; every agent you @mention answers in it
const url = 'http://localhost:11044/api/v1/threads/example/messages';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"attachments":[{"args":{"additionalProperty":"example"},"id":"example","kind":"ENTITY","label":"example","properties":{"additionalProperty":"example"},"title":"example"}],"text":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/threads/example/messages \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "attachments": [ { "args": { "additionalProperty": "example" }, "id": "example", "kind": "ENTITY", "label": "example", "properties": { "additionalProperty": "example" }, "title": "example" } ], "text": "example" }'Attachments are resolved and frozen now: a view is run, a request read, a record taken as you send it.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The thread’s id (a UUIDv7), as returned when it was created or listed by GET /api/v1/threads. Only the caller’s own threads are found; any other id is 404
Request Bodyrequired
Section titled “Request Bodyrequired”The message: text, and attachments resolved and frozen as it is posted (entity a record as the caller saw it, by label, id, title and properties; view the saved view named by label run now with args, keeping up to 25 rows; request the agent request whose id is given). At most 10 attachments are kept, and one that cannot be resolved is dropped. Each @name in the text that matches an agent (case-insensitive) answers in the background, and one that matches none gets a note from the appliance instead; text with no @name at all goes to the agent that spoke last. Blank text with no attachments is 400
A message to post in a thread; sent to POST /threads/{id}/messages. At least one of text and attachments must be non-empty
object
Records, views or requests to attach, resolved and frozen when the message is posted; one that cannot be resolved is dropped, and at most 10 are kept
Something to attach to a thread message, part of the body of POST /threads/{id}/messages. It is resolved when the message is posted: an entity is taken as given, a view is run, a request is read; one that cannot be resolved is dropped.
object
For a view, the arguments to run it with; ignored otherwise
object
For an entity, its key or id; for a request, the id of the request to read (required); ignored for a view
ENTITY, VIEW or REQUEST, matched case-insensitively
For an entity, its label; for a view, the name of the view to run; ignored for a request
For an entity, the record’s properties as the sender sees them; ignored otherwise
object
Card title; blank defaults to the label and id for an entity, the view’s name for a view, and the request’s detail for a request
The message text. Every agent it @mentions answers in the thread in the background; with no mention at all, the agent who spoke last in the thread answers
Responses
Section titled “Responses”The message as posted
One message in a thread, with what it attached. POST /threads/{id}/messages answers the one posted; GET /threads/{id} lists them all, oldest first.
object
Things attached to the message, frozen when it was sent; at most 10
A typed thing from the world attached to a thread message — a record, a view’s rows, or a request — frozen when the message was sent, so the receiver gets the thing rather than a paragraph about it
object
For a view, the arguments it ran with; empty otherwise
object
When the attachment was resolved and frozen, as an ISO-8601 instant; null on one an agent attached without a time
The entity’s key or id, or the request’s id; null for a view
ENTITY for a record, VIEW for a view’s rows, REQUEST for a request awaiting or past a person’s decision
The entity’s label, the view’s name, or request for a request
For an entity, the record’s properties as the sender saw it; for a request, its verb, status (lowercase), routine and args; empty for a view
object
For a view, its rows as run when the message was sent, at most 25; empty otherwise
object
Card title for a person to read; defaults to the label and id for an entity, the view’s name for a view, and the request’s detail for a request
When the message was written, as an ISO-8601 instant
Who wrote it
object
PERSON for the thread’s owner, AGENT for an agent, APPLIANCE for the appliance’s own notices
The person’s username, the agent’s name, or appliance
Message id, a UUIDv7 string, so ids sort in the order the messages were written
Id of the message this one answers; null on a message that answers none, such as a person’s post
Names of the agents this message @mentioned, limited to agents that exist in the world; empty when it addressed none by name
The words of the message; may be empty on a person’s message that only attaches things, and is “(no answer)” when an agent replied with nothing
Id of the thread the message is in
True on an agent’s answer to a message that carried no attachment, so it was given from the words alone
Example
{ "attachments": [ { "kind": "ENTITY" } ], "from": { "kind": "PERSON" }}Nothing to post
No authenticated principal
A refusal with a machine-readable code and a plain-language message. ApiErrorAdvice answers it for a failed validation, a missing resource or a conflicting state, and some controllers answer it directly
object
Machine-readable key to branch on, such as validation_failed, unknown_field, not_found or conflict. Open: a surface may answer codes of its own
Extra context where there is some, such as the fields a body may carry; null otherwise
A plain-language explanation, written to be shown. Never carries an exception message
The body the servlet error dispatch answers for a status raised by an exception rather than written by the endpoint. Every failure except 404, which answers the not-found HTML page
object
The status’s standard reason phrase, such as Bad Request or Forbidden
The request path that failed
The HTTP status code, repeated from the status line
Example generated
{ "code": "example", "detail": "example", "message": "example"}No thread of yours with that id