Skip to content
Embabel Worlds

A thread, its messages, and the agents still answering

GET
/api/v1/threads/{id}
curl --request GET \
  --url http://localhost:11044/api/v1/threads/example \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

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

Responses

Section titled “Responses”

200

Section titled “200”

The thread

Media typeapplication/json

A thread with all its messages and the agents still answering; answered by GET /threads/{id}

object
messages
required

Every message in the thread, oldest first

Array<object>

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
attachments
required

Things attached to the message, frozen when it was sent; at most 10

Array<object>

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
args
required

For a view, the arguments it ran with; empty otherwise

object
key
additional properties
capturedAt

When the attachment was resolved and frozen, as an ISO-8601 instant; null on one an agent attached without a time

string format: date-time
id

The entity’s key or id, or the request’s id; null for a view

string
kind
required

ENTITY for a record, VIEW for a view’s rows, REQUEST for a request awaiting or past a person’s decision

string
Allowed values: ENTITY VIEW REQUEST
label
required

The entity’s label, the view’s name, or request for a request

string
properties
required

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
key
additional properties
rows
required

For a view, its rows as run when the message was sent, at most 25; empty otherwise

Array<object>
object
key
additional properties
title
required

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

string
createdAt
required

When the message was written, as an ISO-8601 instant

string format: date-time
from
required

Who wrote it

object
kind
required

PERSON for the thread’s owner, AGENT for an agent, APPLIANCE for the appliance’s own notices

string
Allowed values: PERSON AGENT APPLIANCE
name
required

The person’s username, the agent’s name, or appliance

string
id
required

Message id, a UUIDv7 string, so ids sort in the order the messages were written

string
inReplyTo

Id of the message this one answers; null on a message that answers none, such as a person’s post

string
mentions
required

Names of the agents this message @mentioned, limited to agents that exist in the world; empty when it addressed none by name

Array<string>
text
required

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

string
threadId
required

Id of the thread the message is in

string
wordsOnly
required

True on an agent’s answer to a message that carried no attachment, so it was given from the words alone

boolean
thread
required

The thread’s own record: its id, owner, title and timestamps, without its messages

object
createdAt
required

When the thread was started, as an ISO-8601 instant

string format: date-time
id
required

Thread id, a UUIDv7 string; the {id} in /threads/{id}

string
ownerId
required

User id of the person who owns the thread; always the caller, since only the owner can read it

string
title
required

Title as given when the thread was started, trimmed; “Untitled” when none was given

string
updatedAt
required

Last activity in the thread, as an ISO-8601 instant; the list is sorted on it, newest first

string format: date-time
waitingOn
required

Names of the agents still working on an answer, sorted; empty when none is. Not kept across a restart, so an answer in progress then is no longer shown as awaited.

Array<string>

Example 

{
  "messages": [
    {
      "attachments": [
        {
          "kind": "ENTITY"
        }
      ],
      "from": {
        "kind": "PERSON"
      }
    }
  ]
}

401

Section titled “401”

No authenticated principal

One of:

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
code
required

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

string
detail

Extra context where there is some, such as the fields a body may carry; null otherwise

string
message
required

A plain-language explanation, written to be shown. Never carries an exception message

string

Example generated

{
  "code": "example",
  "detail": "example",
  "message": "example"
}

404

Section titled “404”

No thread of yours with that id