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 s2s API
version: v1
tags:
- name: s2s
paths:
/api/v1/teams/{team}/invites:
post:
description: 'Generates a new invite code for the specified team using server-to-server
authentication. Unlike the user-facing create endpoint, this variant does not
require the caller to be a team member — it is intended for privileged
back-end services acting on behalf of your platform.
The returned code is a short alphanumeric string that users can present to
join the team. Each call produces a new code; previously issued codes are
not invalidated by this request.'
operationId: post_api_v1_teams__team_invites
parameters:
- description: Team ID (`tm_...`) identifying the team for which to generate the invite code.
example: string
in: path
name: team
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
description: The newly created team invite containing the join code.
example:
code: string
properties:
code:
description: Six-character alphanumeric join code. Present this value to the join-team endpoint to add a user to the team.
example: string
type: string
required:
- code
type: object
description: Successful response
'401':
description: Unauthorized
'404':
description: Team not found
summary: Create a team invite (server-to-server)
tags:
- s2s
x-auth:
- secret_key
/api/v1/teams/{team}/members:
post:
description: '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.'
operationId: post_api_v1_teams__team_members
parameters:
- description: Team ID (`team_...`). The team to add the member to.
example: string
in: path
name: team
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
example:
agent: string
role: string
user: string
properties:
agent:
description: Agent ID (`agt_...`) to add as a member. Provide exactly one of `user` or `agent`.
example: string
type: string
role:
description: Role to assign. One of `"owner"`, `"admin"`, or `"member"`. Defaults to `"member"` when omitted.
example: string
type: string
user:
description: User ID (`usr_...`) to add as a member. Provide exactly one of `user` or `agent`.
example: string
type: string
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TeamMembership'
description: Successful response
'401':
description: Unauthorized
'404':
description: Team or member not found
'422':
description: Validation failed
summary: Add a member to a team
tags:
- s2s
x-auth:
- secret_key
components:
schemas:
ImageSource:
description: Resolved metadata for an image, including its delivery URL, dimensions, and optional references to the underlying storage file or media record.
example:
file: fil_0aBcDeFgHiJkLmNoPqRsTu
height: 600
media: med_0aBcDeFgHiJkLmNoPqRsTu
mime_type: application/json
refresh_url: https://example.com
url: https://example.com
width: 800
properties:
file:
description: ID of the underlying storage file (`fil_...`). `null` when the image is not backed by a platform storage file.
example: fil_0aBcDeFgHiJkLmNoPqRsTu
type: string
height:
description: Height of the image in pixels. `null` if not known.
example: 600
type: integer
media:
description: ID of the associated media record (`med_...`). `null` when the image is not linked to a media entity.
example: med_0aBcDeFgHiJkLmNoPqRsTu
type: string
mime_type:
description: MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`. `null` if not known.
example: application/json
type: string
refresh_url:
description: 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.
example: https://example.com
type: string
url:
description: Signed or public URL for downloading the image. May be time-limited; use `refresh_url` to obtain a new URL when this one expires.
example: https://example.com
type: string
width:
description: Width of the image in pixels. `null` if not known.
example: 800
type: integer
type: object
AclRemoveTarget:
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
Agent:
description: An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or 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
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
properties:
acl:
$ref: '#/components/schemas/Acl'
description: Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope.
app:
description: ID of the application that owns this agent (`dap_...`).
example: dap_0aBcDeFgHiJkLmNoPqRsTu
type: string
created_at:
description: When the agent was created (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
default_model:
description: Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).
example: claude-3-7-sonnet-latest
type: string
email:
description: Email address provisioned for this agent. `null` if email delivery is not configured.
example: user@example.com
type: string
id:
description: Agent ID (`agi_...`).
example: agi_0aBcDeFgHiJkLmNoPqRsTu
type: string
identity:
description: System-level identity prompt that shapes the agent's persona and behavior.
example: You are a helpful assistant that answers questions about ArchAstro products.
type: string
last_applied_template_config:
description: ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.
example: cfg_0aBcDeFgHiJkLmNoPqRsTu
type: string
lookup_key:
description: Stable, user-defined identifier for this agent within the application. Unique per app.
example: string
type: string
metadata:
description: Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.
example:
key: value
type: object
name:
description: Human-readable display name for the agent. `null` if not set.
example: Example Name
type: string
org:
description: ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.
example: org_0aBcDeFgHiJkLmNoPqRsTu
type: string
org_name:
description: 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.
example: Example Name
type: string
originator:
description: Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).
example: deploy-pipeline
type: string
phone_number:
description: Phone number provisioned for this agent. `null` if SMS is not configured.
example: '+15555550123'
type: string
sandbox:
description: ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.
example: dsb_0aBcDeFgHiJkLmNoPqRsTu
type: string
source_solution:
$ref: '#/components/schemas/AgentSourceSolution'
description: Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.
team:
description: ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.
example: tem_0aBcDeFgHiJkLmNoPqRsTu
type: string
updated_at:
description: When the agent was last modified (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
user:
description: ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.
example: usr_0aBcDeFgHiJkLmNoPqRsTu
type: string
required:
- id
type: object
SolutionTemplateSummary:
description: Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity.
example:
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
properties:
description:
description: 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.
example: An example description.
type: string
display_name:
description: 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`.
example: Example Name
type: string
id:
description: Template config ID (`cfg_...`). `null` for inline-only templates.
example: id_0aBcDeFgHiJkLmNoPqRsTu
type: string
kind:
description: Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.
example: AgentTemplate
type: string
lookup_key:
description: Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.
example: string
type: string
name:
description: 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`.
example: Example Name
type: string
readme_url:
description: 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`.
example: https://example.com
type: string
virtual_path:
description: Stable virtual path assigned to the template config. `null` when no virtual path was set.
example: string
type: string
required:
- kind
type: object
TeamMembership:
description: A record representing a user's or agent's membership in a team, including their resolved identity details and role.
example:
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
properties:
agent:
$ref: '#/components/schemas/Agent'
description: The agent associated with this membership, as an expanded agent object. `null` when the member is a user, the type is unknown, or the association is not preloaded.
created_at:
description: When this membership record was created (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
id:
description: Team membership ID (`tmb_...`).
example: tmb_0aBcDeFgHiJkLmNoPqRsTu
type: string
joined_at:
description: When the principal joined the team (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
metadata:
description: Arbitrary key-value metadata attached to this membership record. `null` if no metadata has been set.
example:
key: value
type: object
name:
description: Display name of the member, derived from the associated user or agent. `null` if the principal is unknown.
example: Example Name
type: string
profile_picture:
$ref: '#/components/schemas/ImageSource'
description: Profile picture of the member, derived from the associated user or agent. `null` if not set or principal is unknown.
role:
description: The member's role within the team. One of `"owner"`, `"admin"`, or `"member"`.
example: member
type: string
team:
description: The team this membership belongs to, as an expanded team object. `null` when the team association is not preloaded.
example: {}
type: object
type:
description: Resolved principal type. One of `"user"`, `"agent"`, or `"unknown"` when the principal cannot be determined.
example: user
type: string
updated_at:
description: When this membership record was last updated (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
user:
$ref: '#/components/schemas/User'
description: The user associated with this membership, as an expanded user object. `null` when the member is an agent, the type is unknown, or the association is not preloaded.
required:
- id
type: object
UpgradeTemplateSummary:
description: Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response.
example:
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
properties:
created_at:
description: When this template config was created (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
description:
description: Description of the template from the config body. `null` if the current version has no `description` field.
example: An example description.
type: string
display_name:
description: Human-readable display name from the config body. `null` if the current version has no `display_name` field.
example: Example Name
type: string
id:
description: Template config ID (`cfg_...`).
example: id_0aBcDeFgHiJkLmNoPqRsTu
type: string
kind:
description: Config kind identifier for this template (e.g. `"agent_tool_template"`).
example: agent_tool_template
type: string
lookup_key:
description: Stable lookup key assigned to this template config. `null` if no lookup key is set.
example: string
type: string
name:
description: Template name as stored in the config body. `null` if the current version has no `name` field.
example: Example Name
type: string
updated_at:
description: When this template config was last modified (ISO 8601).
example: '2024-01-01T00:00:00Z'
format: date-time
type: string
virtual_path:
description: Virtual filesystem path for this template config. `null` if not set.
example: string
type: string
required:
- id
- kind
type: object
AgentSourceSolution:
description: '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.'
example:
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
properties:
solution:
$ref: '#/components/schemas/SolutionSummary'
description: Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution.
template:
$ref: '#/components/schemas/UpgradeTemplateSummary'
description: Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.
required:
- solution
- template
type: object
Acl:
description: An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
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`.'
items:
$ref: '#/components/schemas/AclGrant'
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`.'
items:
$ref: '#/components/schemas/AclGrant'
type: array
remove:
description: 'Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.'
items:
$ref: '#/components/schemas/AclRemoveTarget'
type: array
type: object
AclGrant:
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
SolutionSummary:
description: A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information.
example:
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
# --- truncated at 32 KB (1024 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/archastro/refs/heads/main/openapi/archastro-s2s-api-openapi.yml