v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Retrieve a thread

Returns the full thread record for the given thread ID. The authenticated user must own the thread or be a member of the workspace it belongs to.

Use this endpoint to fetch the current state of a single thread, including its title, description, and metadata. To list many threads, use the list endpoint with cursor-based pagination.

get/api/v1/threads/{thread}

Path parameters

threadstring required

Thread ID (thr_...). The authenticated user must have access to this thread.

Response

Successful response

agent_userstring

ID of the agent that owns this thread (agt_...). null for user-owned or team-owned threads.

created_atstring date-time

When the thread was created (ISO 8601).

descriptionstring

Optional description or purpose statement for the thread. null if not set.

idstring required

Thread ID (thr_...).

is_channelboolean

Whether this thread operates as a channel — a multi-member broadcast-style conversation.

is_defaultboolean

Whether this is the default thread for its owner. Each user or team has at most one default thread.

is_transientboolean

Whether this thread is ephemeral and may be deleted automatically after a period of inactivity or when its TTL expires.

is_unlistedboolean

Whether this thread is hidden from public discovery. Unlisted threads are accessible only to direct participants.

keystring

Application-defined stable key that uniquely identifies the thread within its scope. Useful for idempotent creation. null if not set.

last_activitystring date-time

When the last message or activity occurred in this thread. Present only when activity enrichment is requested.

metadataobject

Arbitrary key-value metadata attached to the thread. Shape is application-defined; null if no metadata has been set.

mutedboolean

Whether the authenticated user has muted notifications for this thread. true suppresses all notification delivery.

orgstring

ID of the organization this thread belongs to (org_...). null for threads outside an org context.

participantstring[]

Array of participant user IDs (usr_...) who are members of this thread.

participating_actorstring[]

Composite actor identifiers for all participants currently active in this thread. Present only when actor enrichment is requested.

rolestring

The authenticated user's membership role in this thread, e.g. "owner", "member", or "viewer". null if the user is not a member.

sandboxstring

ID of the developer sandbox this thread is scoped to (sbx_...). null for production threads.

slugstring

URL-safe slug for the thread, used in human-readable permalinks. null if not assigned.

sub_threadsobject[]

Threads that are nested under this thread as replies to a parent message. Present only when sub-thread enrichment is requested.

teamstring

ID of the team that owns this thread (team_...). null for user-owned or agent-owned threads.

titlestring

Human-readable name of the thread. null if no title has been set.

ttlinteger

Time-to-live in seconds after which the thread may be automatically cleaned up. null if the thread does not expire.

unread_countinteger

Number of messages in this thread that the authenticated user has not yet read. Present only when read-state enrichment is requested.

updated_atstring date-time

When the thread was last modified (ISO 8601).

userstring

ID of the user who owns this thread (usr_...). null for team-owned or agent-owned threads.

Example response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "alias": "jdoe",
    "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
    "app_name": "Example Name",
    "email": "user@example.com",
    "id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
    "is_system_user": true,
    "metadata": {
      "key": "value"
    },
    "name": "Example Name",
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "org_name": "Example Name",
    "org_role": "member",
    "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
    "sandbox_name": "Example Name"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "name": "Example Name",
        "profile_picture": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "alias": "jdoe",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "app_name": "Example Name",
      "email": "user@example.com",
      "id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
      "is_system_user": true,
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "org_name": "Example Name",
      "org_role": "member",
      "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox_name": "Example Name"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "acl": {
        "add": [
          {
            "actions": [
              "read",
              "write"
            ],
            "principal": "string",
            "principal_type": "user"
          }
        ],
        "grants": [
          {
            "actions": [
              "read",
              "write"
            ],
            "principal": "string",
            "principal_type": "user"
          }
        ],
        "remove": [
          {
            "principal": "string",
            "principal_type": "user"
          }
        ]
      },
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "default_model": "claude-3-7-sonnet-latest",
      "email": "user@example.com",
      "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "identity": "You are a helpful assistant that answers questions about ArchAstro products.",
      "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "lookup_key": "string",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "org_name": "Example Name",
      "originator": "deploy-pipeline",
      "phone_number": "+15555550123",
      "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
      "source_solution": {
        "solution": {
          "category_keys": [
            "string"
          ],
          "created_at": "2024-01-01T00:00:00Z",
          "description": "An example description.",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "Solution",
          "latest_solution": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "latest_version": "1.0.0",
          "lookup_key": "string",
          "metadata": {
            "key": "value"
          },
          "name": "Example Name",
          "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
          "org_logo": {
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "height": 600,
            "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
            "mime_type": "application/json",
            "refresh_url": "https://example.com",
            "url": "https://example.com",
            "width": 800
          },
          "org_name": "Example Name",
          "org_slug": "example-slug",
          "owners": [
            "string"
          ],
          "readme_url": "https://example.com",
          "solution_id": "01234567-89ab-cdef-0123-456789abcdef",
          "solution_version": "1.2.0",
          "tag_keys": [
            "string"
          ],
          "template_kind": "AgentTemplate",
          "templates": [
            {
              "description": "An example description.",
              "display_name": "Example Name",
              "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
              "kind": "AgentTemplate",
              "lookup_key": "string",
              "name": "Example Name",
              "readme_url": "https://example.com",
              "virtual_path": "string"
            }
          ],
          "updated_at": "2024-01-01T00:00:00Z",
          "upgrade_available": true,
          "virtual_path": "string"
        },
        "template": {
          "created_at": "2024-01-01T00:00:00Z",
          "description": "An example description.",
          "display_name": "Example Name",
          "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
          "kind": "agent_tool_template",
          "lookup_key": "string",
          "name": "Example Name",
          "updated_at": "2024-01-01T00:00:00Z",
          "virtual_path": "string"
        }
      },
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}