openapi: 3.0.0
info:
description: Agent-first API for runtime + developer control-plane operations (users, teams, agents, routines, context, workflows, integrations, and webhooks).
title: ArchAstro Platform Activity Feed Teams API
version: v1
tags:
- name: Teams
paths:
/api/v1/teams:
get:
description: 'Returns a paginated list of teams visible to the authenticated user, ordered
by creation time descending. Use `membership` to narrow results to teams the
caller has joined or teams they are eligible to join based on their ACL
visibility.
Supports full-text search across team name and description via `search`, and
structured metadata filtering via `metadata`. When `app` is present, results
are scoped to that app and the caller must hold the corresponding app scope.'
operationId: get_api_v1_teams
parameters:
- description: Filter teams by membership status. `"joined"` returns only teams the caller is a member of. `"joinable"` returns ACL-visible teams the caller has not yet joined. Omit to return all visible teams.
example: string
in: query
name: membership
required: false
schema:
type: string
- description: Full-text search string matched against team name and description.
example: string
in: query
name: search
required: false
schema:
type: string
- description: Number of teams to return per page. Defaults to 25.
example: 1
in: query
name: page_size
required: false
schema:
type: integer
- description: Page number to retrieve, starting at 1. Defaults to 1.
example: 1
in: query
name: page
required: false
schema:
type: integer
- description: Structured metadata filter expression. Only teams whose metadata satisfies the expression are returned.
in: query
name: metadata
required: false
schema:
description: "A recursive boolean expression tree for filtering records by their JSON metadata field.\n\nEach node is either a group (`and`, `or`, `not`) with nested `clauses`, or a leaf\npredicate (`eq`, `contains`, `exists`) that targets a specific path inside the\nmetadata object. Leaf predicates use `path` (an array of key segments) to address\nnested values.\n\nOperator notes:\n- `eq` performs deep JSONB equality on the value at `path`.\n- `contains` checks whether the stored metadata structurally contains the given value;\n this is the only operator backed by the GIN index and is preferred for performance.\n- `exists` checks whether `path` is present in the metadata object; a key whose value\n is explicitly `null` still satisfies this predicate.\n- `and` and `or` accept two or more `clauses`; `not` accepts exactly one.\n\nThe legacy flat shape (`type: \"metadata\"`, `key`, `value`) is still accepted and is\ntreated as an `eq` predicate. Prefer the structured form for new integrations."
examples:
- clauses:
- clauses:
- operator: eq
path:
- customer_tier
value: enterprise
- operator: exists
path:
- collaborations
- org_123
operator: or
- operator: eq
path:
- type
value: agent_network
operator: and
properties:
clause:
description: Single child expression node. Alternative to `clauses` when `operator` is `not`.
type: object
clauses:
description: Array of child expression nodes. Required for `and` and `or` (two or more items) and `not` (exactly one item).
items:
type: object
type: array
key:
deprecated: true
description: Deprecated. Top-level metadata key; equivalent to a single-element `path`. Use `path` instead.
type: string
operator:
description: The boolean group operator (`and`, `or`, `not`) or leaf predicate operator (`eq`, `contains`, `exists`) for this node.
enum:
- and
- contains
- eq
- exists
- not
- or
type: string
path:
description: Ordered key segments addressing a nested location inside the metadata object, e.g. `["collaborations", "org_123"]`.
items:
type: string
type: array
type:
deprecated: true
description: 'Deprecated. Legacy discriminator; `type: "metadata"` combined with `key`/`value` is treated as an `eq` predicate. Use `operator` instead.'
type: string
value:
description: The JSON value to compare against the node at `path`. Required for `eq` and `contains` predicates; omitted for `exists`.
type: object
responses:
'200':
content:
application/json:
schema:
description: Paginated list of teams matching the query.
example:
data:
- 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
badges: {}
created_at: '2024-01-01T00:00:00Z'
description: An example description.
id: tem_0aBcDeFgHiJkLmNoPqRsTu
membership_status: member
metadata:
key: value
name: Example Name
org: org_0aBcDeFgHiJkLmNoPqRsTu
sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
slug: example-slug
updated_at: '2024-01-01T00:00:00Z'
has_next: true
has_prev: true
page: 1
page_size: 1
total_entries: 1
total_pages: 1
properties:
data:
description: Array of team objects for the current page.
example:
- 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
badges: {}
created_at: '2024-01-01T00:00:00Z'
description: An example description.
id: tem_0aBcDeFgHiJkLmNoPqRsTu
membership_status: member
metadata:
key: value
name: Example Name
org: org_0aBcDeFgHiJkLmNoPqRsTu
sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
slug: example-slug
updated_at: '2024-01-01T00:00:00Z'
items:
description: A team within an organization, used to group users and agents and scope resources like configs, agents, and tasks.
example:
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
badges: {}
created_at: '2024-01-01T00:00:00Z'
description: An example description.
id: tem_0aBcDeFgHiJkLmNoPqRsTu
membership_status: member
metadata:
key: value
name: Example Name
org: org_0aBcDeFgHiJkLmNoPqRsTu
sandbox: dsb_0aBcDeFgHiJkLmNoPqRsTu
slug: example-slug
updated_at: '2024-01-01T00:00:00Z'
properties:
acl:
description: Access control list governing visibility and join permissions for this team. `null` when no ACL restrictions are applied and the team inherits default access rules.
example:
add:
- actions:
- read
- write
principal: string
principal_type: user
grants:
- actions:
- read
- write
principal: string
principal_type: user
remove:
- principal: string
principal_type: user
properties:
add:
description: 'Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
grants:
description: '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`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
remove:
description: 'Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.'
example:
- principal: string
principal_type: user
items:
description: Identifies a principal to be removed from an access-control list.
example:
principal: string
principal_type: user
properties:
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- principal_type
type: object
type: array
type: object
app:
description: ID of the developer application this team belongs to (`dap_...`). `null` if the team is not scoped to an app.
example: dap_0aBcDeFgHiJkLmNoPqRsTu
type: string
badges:
description: Aggregated badge counts for the team, keyed by category. `null` when badge data is not loaded.
example: {}
type: object
created_at:
description: When this team was created (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
description:
description: Human-readable description of the team's purpose. `null` if not set.
example: An example description.
type: string
id:
description: Team ID (`tem_...`).
example: tem_0aBcDeFgHiJkLmNoPqRsTu
type: string
membership_status:
description: The authenticated viewer's role on this team. One of `"owner"`, `"admin"`, or `"member"`. `null` if the viewer is not a member.
example: member
type: string
metadata:
description: Arbitrary key-value metadata attached to this team. Returns an empty object when no metadata has been set.
example:
key: value
type: object
name:
description: Display name of the team.
example: Example Name
type: string
org:
description: ID of the organization this team belongs to (`org_...`). `null` if the team is not org-scoped.
example: org_0aBcDeFgHiJkLmNoPqRsTu
type: string
sandbox:
description: ID of the developer sandbox this team is scoped to (`dsb_...`). `null` outside sandbox contexts.
example: dsb_0aBcDeFgHiJkLmNoPqRsTu
type: string
slug:
description: URL-safe slug for the team, derived from the team name. `null` if not set.
example: example-slug
type: string
updated_at:
description: When this team was last updated (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
required:
- id
type: object
type: array
has_next:
description: '`true` if there is a subsequent page of results.'
example: true
type: boolean
has_prev:
description: '`true` if there is a preceding page of results.'
example: true
type: boolean
page:
description: The current page number.
example: 1
type: integer
page_size:
description: The number of results per page.
example: 1
type: integer
total_entries:
description: Total number of teams matching the query across all pages.
example: 1
type: integer
total_pages:
description: Total number of pages given the current `page_size`.
example: 1
type: integer
required:
- data
- has_next
- has_prev
- page
- page_size
- total_entries
- total_pages
type: object
description: Successful response
'400':
description: Bad request - invalid metadata filter
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
summary: List teams
x-auth:
- bearer
- publishable_key
tags:
- Teams
post:
description: 'Creates a new team and returns the created team object. The authenticated
user becomes the team''s owner.
When `app` is supplied, the request is scoped to that app and the caller
must hold the corresponding app scope. Omit `org` unless you want the team
pinned to a specific organization. A default chat thread is provisioned for
the team automatically after creation.'
operationId: post_api_v1_teams
parameters: []
requestBody:
content:
application/json:
schema:
example:
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
description: An example description.
metadata:
key: value
name: Example Name
org: string
properties:
acl:
description: Access control configuration for the team. Controls who can discover and join the team.
example:
add:
- actions:
- read
- write
principal: string
principal_type: user
grants:
- actions:
- read
- write
principal: string
principal_type: user
remove:
- principal: string
principal_type: user
properties:
add:
description: 'Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
grants:
description: '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`.'
example:
- actions:
- read
- write
principal: string
principal_type: user
items:
description: A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
example:
actions:
- read
- write
principal: string
principal_type: user
properties:
actions:
description: Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.
example:
- read
- write
items:
type: string
type: array
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- actions
- principal_type
type: object
type: array
remove:
description: 'Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.'
example:
- principal: string
principal_type: user
items:
description: Identifies a principal to be removed from an access-control list.
example:
principal: string
principal_type: user
properties:
principal:
description: 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"`.
example: string
type: string
principal_type:
description: The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.
example: user
type: string
required:
- principal_type
type: object
type: array
type: object
description:
description: Optional human-readable description of the team's purpose.
example: An example description.
type: string
metadata:
description: Arbitrary key-value pairs you can attach to the team for your own use. Values must be strings.
example:
key: value
type: object
name:
description: Display name for the team.
example: Example Name
type: string
org:
description: Organization ID (`org_...`) to associate the team with. Omit to create the team without an org affiliation.
example: string
type: string
required:
- name
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Team'
description: Successful response
'401':
description: Unauthorized
'403':
description: Forbidden - app scope required
'422':
description: Validation failed
summary: Create a team
x-auth:
- bearer
- publishable_key
tags:
- Teams
/api/v1/teams/join_by_code:
post:
description: 'Adds a principal to a team using a 12-character invite code. The invite
code can be supplied as either `join_code` or `invite_code`; both are
accepted for backwards compatibility.
For user-authenticated requests, the currently authenticated user is added
to the team. For server-to-server requests, you must supply either `agent`
(to add an agent) or `user` (to add a specific user by ID). If the user
is already a member of the team, the request succeeds without creating a
duplicate membership.
This endpoint is rate-limited to 10 requests per minute per IP address to
prevent invite-code enumeration.'
operationId: post_api_v1_teams_join_by_code
parameters: []
requestBody:
content:
application/json:
schema:
example:
agent: string
invite_code: string
join_code: string
user: string
properties:
agent:
description: Agent ID (`agent_...`) to add to the team. When provided, the agent is joined instead of the authenticated user. Requires a server-to-server session.
example: string
type: string
invite_code:
description: 12-character invite code — alias for `join_code` accepted for backwards compatibility.
example: string
type: string
join_code:
description: 12-character invite code that identifies the team. Mutually usable with `invite_code`.
example: string
type: string
user:
description: User ID (`user_...`) to add to the team. Required for server-to-server requests when `agent` is not supplied.
example: string
# --- truncated at 32 KB (1375 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-teams-api-openapi.yml