v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

s2s

Add a member to a team

Adds a user or agent as a member of the specified team and returns the new membership with HTTP 201. Provide exactly one of user or agent — supplying both or neither returns a 400 error.

The caller must have permission to manage the team. When an app is provided, the request is scoped to that app and the caller must hold a valid app-scoped token. The default role is "member" when role is omitted.

post/api/v1/teams/{team}/members

Path parameters

teamstring required

Team ID (team_...). The team to add the member to.

Request body

agentstring

Agent ID (agt_...) to add as a member. Provide exactly one of user or agent.

rolestring

Role to assign. One of "owner", "admin", or "member". Defaults to "member" when omitted.

userstring

User ID (usr_...) to add as a member. Provide exactly one of user or agent.

Example request

{
  "agent": "string",
  "role": "string",
  "user": "string"
}

Response

Successful response

created_atstring date-time

When this membership record was created (ISO 8601).

idstring required

Team membership ID (tmb_...).

joined_atstring date-time

When the principal joined the team (ISO 8601).

metadataobject

Arbitrary key-value metadata attached to this membership record. null if no metadata has been set.

namestring

Display name of the member, derived from the associated user or agent. null if the principal is unknown.

rolestring

The member's role within the team. One of "owner", "admin", or "member".

teamobject

The team this membership belongs to, as an expanded team object. null when the team association is not preloaded.

typestring

Resolved principal type. One of "user", "agent", or "unknown" when the principal cannot be determined.

updated_atstring date-time

When this membership record was last updated (ISO 8601).

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"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "id": "tmb_0aBcDeFgHiJkLmNoPqRsTu",
  "joined_at": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "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
  },
  "role": "member",
  "team": {},
  "type": "user",
  "updated_at": "2024-01-01T00:00:00Z",
  "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"
  }
}