---
title: "Add a member to a thread"
method: POST
path: "/api/v1/threads/{thread}/members"
---

# Add a member to a thread

`POST /api/v1/threads/{thread}/members`

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.

## Path parameters

- `thread` string, required

## Request body

- object
  - `agent` string — Agent ID of the principal to add. Required when `type` is `"agent"`.
  - `membership_type` string — Role granted to the new member. One of `"owner"` or `"member"`. Defaults to `"member"`.
  - `type` string, required — Kind of principal being added. Must be `"user"` or `"agent"`.
  - `user` string — User ID of the principal to add. Required when `type` is `"user"`.

## Response `201`

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

- ChatMember — A participant in a chat thread, which may be either a human user or an AI agent. Exactly one of `user` or `agent` is populated depending on `type`.
  - `agent` Agent — An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks.
    - `acl` Acl — An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
      - `add` AclGrant[] — Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.
        - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
        - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
        - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
      - `grants` AclGrant[] — Replace mode: the complete new list of grants that replaces all existing entries. Send an empty array (`[]`) to clear all grants. Cannot be combined with `add` or `remove`.
        - `actions` string[], required — Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
        - `principal` string — The identifier of the principal. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`; omit entirely when `principal_type` is `"everyone"`.
        - `principal_type` string, required — The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
      - `remove` AclRemoveTarget[] — Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.
        - `principal` string — The identifier of the principal to remove. A string ID for `"user"`, `"team"`, `"org"`, and `"agent"` types; one of `"admin"`, `"member"`, or `"viewer"` for `"org_role"`. Omit when `principal_type` is `"everyone"`.
        - `principal_type` string, required — The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
    - `app` string — ID of the application that owns this agent (`dap_...`).
    - `created_at` string, date-time — When the agent was created (ISO 8601).
    - `default_model` string — Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).
    - `email` string — Email address provisioned for this agent. `null` if email delivery is not configured.
    - `id` string, required — Agent ID (`agi_...`).
    - `identity` string — System-level identity prompt that shapes the agent's persona and behavior.
    - `last_applied_template_config` string — ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.
    - `lookup_key` string — Stable, user-defined identifier for this agent within the application. Unique per app.
    - `metadata` object — Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.
    - `name` string — Human-readable display name for the agent. `null` if not set.
    - `org` string — ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.
    - `org_name` string — Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.
    - `originator` string — Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).
    - `phone_number` string — Phone number provisioned for this agent. `null` if SMS is not configured.
    - `sandbox` string — ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.
    - `source_solution` AgentSourceSolution — Summary of the Solution and AgentTemplate that an agent was last provisioned from. Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted.
      - `solution` SolutionSummary, required — A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information.
        - `category_keys` string[] — Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
        - `created_at` string, date-time — When the Solution config was first imported (ISO 8601).
        - `description` string — Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.
        - `id` string, required — Solution config ID (`cfg_...`).
        - `kind` string, required — Resource type. Always `"Solution"`.
        - `latest_solution` string — When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.
        - `latest_version` string — When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.
        - `lookup_key` string — The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.
        - `metadata` object — Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
        - `name` string — Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.
        - `org` string — Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.
        - `org_logo` ImageSource — Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
          - `file` string — ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
          - `height` integer — Height of the image in pixels. `null` if not known.
          - `media` string — ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
          - `mime_type` string — MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
          - `refresh_url` string — Endpoint URL you can call to obtain a fresh signed `url` when the current one has expired. `null` if the URL does not require refreshing.
          - `url` string — Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
          - `width` integer — Width of the image in pixels. `null` if not known.
        - `org_name` string — Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.
        - `org_slug` string — Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key — clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.
        - `owners` string[], required — Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer's org scope).
        - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.
        - `solution_id` string — Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.
        - `solution_version` string — Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.
        - `tag_keys` string[] — Freeform tag keys declared in the Solution body. An empty array when the body declares none.
        - `template_kind` string — Wrapped template kind — `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.
        - `templates` SolutionTemplateSummary[], required — Template configs bundled by this Solution, in declaration order — the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.
          - `description` string — Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.
          - `display_name` string — Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.
          - `id` string — Template config ID (`cfg_...`). `null` for inline-only templates.
          - `kind` string, required — Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.
          - `lookup_key` string — Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.
          - `name` string — Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.
          - `readme_url` string — Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour — refresh via `GET /api/v1/solutions/:solution`.
          - `virtual_path` string — Stable virtual path assigned to the template config. `null` when no virtual path was set.
        - `updated_at` string, date-time — When the Solution config was last modified (ISO 8601).
        - `upgrade_available` boolean, required — `true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.
        - `virtual_path` string — The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.
      - `template` UpgradeTemplateSummary, required — Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response.
        - `created_at` string, date-time — When this template config was created (ISO 8601).
        - `description` string — Description of the template from the config body. `null` if the current version has no `description` field.
        - `display_name` string — Human-readable display name from the config body. `null` if the current version has no `display_name` field.
        - `id` string, required — Template config ID (`cfg_...`).
        - `kind` string, required — Config kind identifier for this template (e.g. `"agent_tool_template"`).
        - `lookup_key` string — Stable lookup key assigned to this template config. `null` if no lookup key is set.
        - `name` string — Template name as stored in the config body. `null` if the current version has no `name` field.
        - `updated_at` string, date-time — When this template config was last modified (ISO 8601).
        - `virtual_path` string — Virtual filesystem path for this template config. `null` if not set.
    - `team` string — ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.
    - `updated_at` string, date-time — When the agent was last modified (ISO 8601).
    - `user` string — ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.
  - `membership_type` string — Role of this member within the thread. Common values are `"owner"` and `"member"`. `null` when the membership type is not applicable.
  - `type` string, required — Kind of participant. One of `"user"` (a human user) or `"agent"` (an AI agent).
  - `user` User — A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.
    - `alias` string — Short handle or alias for the user. `null` if not set.
    - `app` string — ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.
    - `app_name` string — Display name of the user's app. `null` when the app association was not preloaded by the caller.
    - `email` string — Email address of the user.
    - `id` string, required — User ID (`usr_...`).
    - `is_system_user` boolean — `true` if this account is an internal system user rather than a human. System users are created automatically by the platform.
    - `metadata` object — Arbitrary key-value metadata attached to the user. Defaults to an empty object.
    - `name` string — Full display name of the user. `null` if the user has not set a name.
    - `org` string — ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.
    - `org_name` string — Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.
    - `org_role` string — Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.
    - `sandbox` string — ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.
    - `sandbox_name` string — Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.

## Other responses

- `401` — Unauthorized
- `403` — Forbidden - not allowed to add members to this thread
- `404` — Thread not found
- `422` — Failed to add member

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/versions/a8772b442f86/schema)