Threads

Threads represent collections of messages exchanged between various actors and agents.

Thread object

Attributes

id

String

A unique identifier for the thread, used to reference it across the system.

agent_id

String

The unique identifier for the agent associated with the thread.

instance_id

String

The unique identifier for the instance within which the thread exists.

timezone

Object

The timezone information for the thread, useful for contextualizing timestamps.

country

Object

Information about the country associated with the thread.

language

Object

Information about the language used in the thread.

metadata

Object

Additional metadata for the thread, which can be custom-defined.

participants

Array of Objects

An array of participants involved in the thread, including users, assistants, or tools.

created_at

Date

The timestamp when the thread was created.

updated_at

Date

The timestamp of the last update to the thread.

{
  "id": "thread_Rm4Mnheq2bfEPhBhP7SY",
  "agent_id": "agent_Rm4Mnheq2bfEPhBhP7SY",
  "instance_id": "instance_Rm4Mnheq2bfEPhBhP7SY",
  "timezone": {
    "code": "America/New_York",
    "utc": "-05:00",
    "utc_offset_in_minutes": -300
  },
  "country": {
    "code": "US"
  },
  "language": {
    "code": "en"
  },
  "metadata": {},
  "participants": [
    {
      "id": "act_Rm4Mnheq2bfEPhBhP7SY",
      "name": "John Doe",
      "type": "user",
      "metadata": {
        "email": "[email protected]",
        "other": "Additional metadata can be included here."
      },
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z",
      "role": "read_write",
      "joined_at": "2025-01-01T00:00:00.000Z",
      "thread_id": "thread_Rm4Mnheq2bfEPhBhP7SY"
    }
  ],
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-01T00:00:00.000Z"
}

List threads

Retrieve a list of all threads in the system.

Query Parameters

id

ObjectOptional

Filter threads by their unique identifiers.

created_at

ObjectOptional

Filter threads by their creation date.

updated_at

ObjectOptional

Filter threads by their last update date.

GEThttps://api.metorial.com/threads
curl -X GET https://api.metorial.com/threads \
  -H "Authorization: Bearer metorial_sk_..."

Get thread

Retrieve details of a specific thread by its unique ID.

URL Parameters

threadId

String

The unique identifier for a thread.

GEThttps://api.metorial.com/threads/:threadId
curl -X GET "https://api.metorial.com/v1/threads/thread_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."

Create thread

Create a new thread and associate it with an agent.

Request Body

language

StringOptional

The language of the messages within the thread.

country

StringOptional

The country associated with the thread.

timezone

StringOptional

The timezone for the thread.

metadata

ObjectOptional

Custom metadata for the thread.

actor_id

StringOptional

The unique identifier of the actor initiating the thread.

agent_id

String

The agent with which the thread is associated.

POSThttps://api.metorial.com/threads
curl -X POST "https://api.metorial.com/v1/threads" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
    "agent_id": "agent_Rm4Mnheq2bfEPhBhP7SY",
    "actor_id": "actor_q2bfShBRmEPnhehP74MY",
    "language": "en",
    "country": "US",
    "timezone": "America/New_York"
  }'

Update thread

Update details of an existing thread by its unique ID.

URL Parameters

threadId

String

The unique identifier for a thread.

Request Body

metadata

ObjectOptional

Additional metadata to update for the thread.

PUThttps://api.metorial.com/threads/:threadId
curl -X PUT "https://api.metorial.com/v1/threads/thread_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..." \
  -d '{
    "metadata": {
      "other": "Additional metadata"
    }
  }'

Delete thread

Delete a thread by its unique ID.

URL Parameters

threadId

String

The unique identifier for a thread.

DELETEhttps://api.metorial.com/threads/:threadId
curl -X DELETE "https://api.metorial.com/v1/threads/thread_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer $$SECRET"