Sign in

v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create a thread for an agent

Creates a new thread owned by the specified agent. The thread is scoped to the agent's identity and is immediately available for messaging.

The authenticated caller must have access to the agent's parent app. If your API key is scoped to a specific app, pass that app's ID via the app parameter. Attempting to create a thread for an agent you cannot access returns 404.

By default the platform may send an automatic welcome message into the new thread. Pass skip_welcome_message: true to suppress this behavior.

post/api/v1/agents/{agent}/threads

Path parameters

agentstring required

Agent ID (agt_...). The thread will be owned by this agent.

Request body

skip_welcome_messageboolean

When true, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to false.

Example request

{
  "skip_welcome_message": true,
  "thread": {
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org": "string",
    "settings": {},
    "title": "Example Title"
  }
}

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