v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Add a member to a thread

Adds a user or agent to the explicit roster of a private or restricted thread. Team-visible threads use the owning team's implicit roster and reject explicit additions. On restricted threads, a team member may add themself; adding anyone else requires permission to modify the thread.

Supply either user or agent depending on the value of type. Targets must be visible to the caller and, for an ordinary team-owned thread, must belong to the owning team. On success the membership record is returned with HTTP 201; repeated agent additions are idempotent.

post/api/v1/threads/{thread}/members

Path parameters

threadstring required

Thread ID (thr_...) identifying the thread to add the member to.

Request body

agentstring

Agent ID of the principal to add. Required when type is "agent".

membership_typestring

Role granted to the new member. One of "owner" or "member". Defaults to "member".

typestring required

Kind of principal being added. Must be "user" or "agent".

userstring

User ID of the principal to add. Required when type is "user".

Example request

{
  "agent": "string",
  "membership_type": "string",
  "type": "string",
  "user": "string"
}

Response

The user or agent membership that was added to the thread.

membership_typestring

Role of this member within the thread. Common values are "owner" and "member". null when the membership type is not applicable.

typestring required

Kind of participant. One of "user" (a human user) or "agent" (an AI agent).

Example response

{
  "agent": {
    "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"
  },
  "membership_type": "owner",
  "type": "user",
  "user": {
    "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"
  }
}