Sign in

v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Update a thread

Updates one or more mutable properties of the specified thread and returns the full thread object with the applied changes. Only the fields you provide are modified; omitted fields retain their current values.

If profile_picture is supplied, the image is uploaded before the other fields are saved, after all ordinary thread fields have passed validation. Supplying invalid base64 picture data returns 422 and no other fields are updated.

Visibility can only widen: private may become restricted or team, and restricted may become team. The authenticated viewer must have permission to modify the thread.

put/api/v1/threads/{thread}

Path parameters

threadstring required

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

Request body

descriptionstring

Optional longer text describing the thread's purpose. Replaces the existing description when provided.

metadataobject

Arbitrary key-value metadata to store on the thread. Merged with or replaces existing metadata.

mutedboolean

When true, suppresses notifications for new messages in this thread for the authenticated user.

titlestring

Human-readable display name for the thread. Replaces the existing title when provided.

visibility'private' | 'restricted' | 'team'

Widen a team-owned thread: private may become restricted or team, and restricted may become team. Visibility cannot be narrowed.

Example request

{
  "description": "An example description.",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "title": "Example Title",
  "visibility": "private"
}

Response

The thread object after the update has been applied.

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"
}