API Reference

Public endpoints generated from the reviewed external OpenAPI spec. Use this page for human scanning, and use openapi.json for SDKs, tools, and automation.

65 paths89 operations30 channel eventsOpenAPI 3.0.0external scope

Base URL

https://developers.archastro.ai

Authentication

Use the auth scheme declared on each endpoint.

Channels

Realtime channels use bearer auth.

Spec

Download OpenAPI JSON

/api/v1/activity_feed

Activity Feed

1 operations

GET/api/v1/activity_feed

List activity feed entries

Returns a cursor-paginated list of activity feed entries visible to the authenticated user. Entries are ordered from newest to oldest by default. Use `before_cursor` to page backward and `after_cursor` to page forward. Results are scoped to the caller's app. All filter params are optional and can be combined. Passing multiple values in an array filter returns entries matching any of the supplied values (OR semantics). Invalid `kind` or `level` values return a 400 error listing the accepted values rather than being silently ignored.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`limit`query	integer	Maximum number of entries to return per page. Defaults to 50; maximum is 100.
`kind`query	array<string>	One or more entry kinds to include. Accepted values: routine_run, automation_run, thread_story, agent_quality_verdict, generic. Omit to return all kinds.
`level`query	array<string>	One or more severity levels to include. Accepted values: debug, info, warn, error, audit. Omit to return all levels.
`after_cursor`query	string	Opaque cursor from a previous response's `after_cursor` field. Returns entries newer than the cursor's position.
`before_cursor`query	string	Opaque cursor from a previous response's `before_cursor` field. Returns entries older than the cursor's position.
`agent`query	array<string>	Restrict results to entries associated with these agent IDs (`agt_...`). Accepts multiple values.
`org`query	array<string>	Restrict results to entries associated with these organization IDs (`org_...`). Accepts multiple values.
`team`query	array<string>	Restrict results to entries associated with these team IDs (`tem_...`). Accepts multiple values.
`thread`query	array<string>	Restrict results to entries associated with these thread IDs (`thr_...`). Accepts multiple values.
`correlation_id`query	string	Restrict results to entries that share this correlation group identifier. Useful for tracing a chain of related events.

Responses

200Successful response
400Invalid cursor
401Unauthorized
403App-scoped token required. Use a token scoped to the target app.

curl

curl -X GET https://developers.archastro.ai/api/v1/activity_feed \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.activity_feed.list({ limit: 1, kind: ["string"], level: ["string"], afterCursor: "string", beforeCursor: "string", agent: ["string"], org: ["string"], team: ["string"], thread: ["string"], correlationId: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.activity_feed.list(limit=1, kind=["string"], level=["string"], after_cursor="string", before_cursor="string", agent=["string"], org=["string"], team=["string"], thread=["string"], correlation_id="string")

Response

{
  "after_cursor": "string",
  "before_cursor": "string",
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "attachments": [
        {}
      ],
      "automation_run": "atr_0aBcDeFgHiJkLmNoPqRsTu",
      "content": "The agent completed the task successfully.",
      "correlation_id": "01234567-89ab-cdef-0123-456789abcdef",
      "created_at": "2024-01-01T00:00:00Z",
      "id": "afe_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "agent_step",
      "level": "info",
      "metadata": {
        "key": "value"
      },
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "routine_run": "arr_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox": "string",
      "session_record": "ase_0aBcDeFgHiJkLmNoPqRsTu",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "title": "Example Title",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  ],
  "has_more": true
}

/api/v1/agents

Agents

24 operations

GET/api/v1/agents

List agents

Returns a paginated list of agents visible to the authenticated caller. Results are ordered by creation time descending. Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` to scope the list to a specific owner. Use `template_config` to find agents whose last applied template matches a given config ID. Pagination is page-based: pass `page` and `page_size` to navigate through large result sets. When called under a developer app scope, only agents belonging to that app are returned.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`template_config`query	string	Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches.
`search`query	string	Free-text search string matched against the agent name, org, team, and owner fields.
`page_size`query	integer	Number of agents to return per page. Defaults to `25`.
`org_id`query	string	Organization ID (`org_...`) to filter by. Returns only agents owned by this org.
`page`query	integer	Page number to retrieve, 1-indexed. Defaults to `1`.
`user`query	string	User ID (`usr_...`) to filter by. Returns only agents owned by this user.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required

curl

curl -X GET https://developers.archastro.ai/api/v1/agents \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.list({ templateConfig: "string", search: "string", pageSize: 1, orgId: "string", page: 1, user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.list(template_config="string", search="string", page_size=1, org_id="string", page=1, user="string")

Response

{
  "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",
      "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"
    }
  ],
  "has_next": true,
  "has_prev": true,
  "page": 1,
  "page_size": 20,
  "total_entries": 42,
  "total_pages": 1
}

POST/api/v1/agents

Create an agent

Creates a new agent. Supports two mutually exclusive provisioning modes. **Template mode** — pass `template` with the ID or `lookup_key` of an existing AgentTemplate config. The agent's tools, routines, skills, and installations are provisioned from that template's `config_ref` entries. **Bundle mode** — pass `template_bundle` with a self-contained install payload (AgentTemplate body plus every skill, script, and config it references). The entire bundle commits in a single transaction; any failure rolls back the whole install and the response includes `installed_configs[]` — one entry per persisted config. Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` is required and a blank agent is created. Requires authentication; when called under a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope for the target app.

Bearer tokenPublishable key

Request body

Name	Type	Description
`acl`	object	Access control list controlling which users, teams, or orgs can read or manage this agent.
`email`	string	Email address assigned to the agent. Used as the agent's contact identity.
`identity`	string	System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn.
`lookup_key`	string	Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org.
`metadata`	object	Arbitrary key-value map stored on the agent. Not interpreted by the platform.
`model`	string	Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model.
`name`	string	Display name for the agent. Required when neither `template` nor `template_bundle` is provided.
`org`	string	Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`.
`originator`	string	Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug.
`phone_number`	string	Phone number assigned to the agent in E.164 format, e.g. `+15550001234`.
`profile_picture`	object	Profile picture to attach to the agent. All three subfields are required when this object is present.
`team`	string	Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`.
`template`	string	ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`.
`template_bundle`	object	Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`.
`user`	string	User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`.

Responses

200Successful response
400Bad request
401Unauthorized
403Forbidden — app scope required
404Template not found
409Conflict
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "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"
      }
    ]
  },
  "email": "user@example.com",
  "identity": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "model": "string",
  "name": "Example Name",
  "org": "string",
  "originator": "string",
  "phone_number": "+15555550123",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "team": "string",
  "template": "string",
  "template_bundle": {
    "configs": [
      {
        "content": "string",
        "content_type": "application/json",
        "relative_path": "tools/my-tool.yaml"
      }
    ],
    "lookup_key_suffix": "string",
    "setup_actions": [
      {
        "depends_on": [
          "string"
        ],
        "description": "An example description.",
        "kind": "env_var",
        "params": {
          "key": "value"
        },
        "required": true,
        "sort_order": 1,
        "title": "Example Title",
        "verify_config": {
          "key": "value"
        }
      }
    ],
    "skills": [
      {
        "content": "string",
        "content_type": "application/json",
        "files": [
          {
            "content": "string",
            "content_type": "application/json",
            "relative_path": "skills/my-skill/helpers.md"
          }
        ],
        "relative_path": "skills/my-skill/SKILL.md"
      }
    ],
    "template": {
      "content": "string",
      "content_type": "application/json",
      "relative_path": "agent.yaml"
    }
  },
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.create({ 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" }] }, email: "user@example.com", identity: "string", lookup_key: "string", metadata: { key: "value" }, model: "string", name: "Example Name", org: "string", originator: "string", phone_number: "+15555550123", profile_picture: { data: "string", filename: "string", mime_type: "application/json" }, team: "string", template: "string", template_bundle: { configs: [{ content: "string", content_type: "application/json", relative_path: "tools/my-tool.yaml" }], lookup_key_suffix: "string", setup_actions: [{ depends_on: ["string"], description: "An example description.", kind: "env_var", params: { key: "value" }, required: true, sort_order: 1, title: "Example Title", verify_config: { key: "value" } }], skills: [{ content: "string", content_type: "application/json", files: [{ content: "string", content_type: "application/json", relative_path: "skills/my-skill/helpers.md" }], relative_path: "skills/my-skill/SKILL.md" }], template: { content: "string", content_type: "application/json", relative_path: "agent.yaml" } }, user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.create({"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"}]}, "email": "user@example.com", "identity": "string", "lookup_key": "string", "metadata": {"key": "value"}, "model": "string", "name": "Example Name", "org": "string", "originator": "string", "phone_number": "+15555550123", "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}, "team": "string", "template": "string", "template_bundle": {"configs": [{"content": "string", "content_type": "application/json", "relative_path": "tools/my-tool.yaml"}], "lookup_key_suffix": "string", "setup_actions": [{"depends_on": ["string"], "description": "An example description.", "kind": "env_var", "params": {"key": "value"}, "required": True, "sort_order": 1, "title": "Example Title", "verify_config": {"key": "value"}}], "skills": [{"content": "string", "content_type": "application/json", "files": [{"content": "string", "content_type": "application/json", "relative_path": "skills/my-skill/helpers.md"}], "relative_path": "skills/my-skill/SKILL.md"}], "template": {"content": "string", "content_type": "application/json", "relative_path": "agent.yaml"}}, "user": "string"})

JSON body

{
  "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"
      }
    ]
  },
  "email": "user@example.com",
  "identity": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "model": "string",
  "name": "Example Name",
  "org": "string",
  "originator": "string",
  "phone_number": "+15555550123",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "team": "string",
  "template": "string",
  "template_bundle": {
    "configs": [
      {
        "content": "string",
        "content_type": "application/json",
        "relative_path": "tools/my-tool.yaml"
      }
    ],
    "lookup_key_suffix": "string",
    "setup_actions": [
      {
        "depends_on": [
          "string"
        ],
        "description": "An example description.",
        "kind": "env_var",
        "params": {
          "key": "value"
        },
        "required": true,
        "sort_order": 1,
        "title": "Example Title",
        "verify_config": {
          "key": "value"
        }
      }
    ],
    "skills": [
      {
        "content": "string",
        "content_type": "application/json",
        "files": [
          {
            "content": "string",
            "content_type": "application/json",
            "relative_path": "skills/my-skill/helpers.md"
          }
        ],
        "relative_path": "skills/my-skill/SKILL.md"
      }
    ],
    "template": {
      "content": "string",
      "content_type": "application/json",
      "relative_path": "agent.yaml"
    }
  },
  "user": "string"
}

Response

{
  "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-5-sonnet-20241022",
  "email": "user@example.com",
  "id": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "identity": "You are a helpful assistant.",
  "installed_configs": [
    {
      "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
      "key": "my-skill",
      "kind": "Skill",
      "lookup_key": "my-skill"
    }
  ],
  "lookup_key": "my-agent",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "originator": "my-service",
  "phone_number": "+15555550123",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

GET/api/v1/agents/{agent}

Retrieve an agent

Returns the agent identified by ID or `lookup_key`. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the agent must belong to that app. Use the list endpoint to retrieve many agents at once.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent to retrieve.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.get("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.get("string")

Response

{
  "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"
}

PATCH/api/v1/agents/{agent}

Update an agent

Updates one or more fields on an existing agent. Only the fields you supply are changed; omitted fields retain their current values. To clear the agent's default model, pass `model` as an empty string. The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent to update.

Request body

Name	Type	Description
`acl`	object	Replacement access control list. Fully replaces the existing ACL.
`email`	string	New email address for the agent.
`identity`	string	Replacement identity system-prompt string describing who the agent is.
`lookup_key`	string	New `lookup_key` slug. Must be unique within the owning app or org.
`metadata`	object	Replacement key-value metadata map. The entire map is replaced, not merged.
`model`	string	New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model.
`name`	string	New display name for the agent.
`org`	string	Organization ID (`org_...`) to transfer ownership to.
`originator`	string	Replacement originator label identifying the source or author of the agent.
`phone_number`	string	New phone number for the agent in E.164 format, e.g. `+15550001234`.
`profile_picture`	object	Replacement profile picture. All three subfields are required when this object is present.
`team`	string	Team ID (`team_...`) to transfer ownership to.
`user`	string	User ID (`usr_...`) to transfer ownership to.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found
422Validation failed

curl

curl -X PATCH https://developers.archastro.ai/api/v1/agents/{agent} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "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"
      }
    ]
  },
  "email": "user@example.com",
  "identity": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "model": "string",
  "name": "Example Name",
  "org": "string",
  "originator": "string",
  "phone_number": "+15555550123",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "team": "string",
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.update("string", { 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" }] }, email: "user@example.com", identity: "string", lookup_key: "string", metadata: { key: "value" }, model: "string", name: "Example Name", org: "string", originator: "string", phone_number: "+15555550123", profile_picture: { data: "string", filename: "string", mime_type: "application/json" }, team: "string", user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.update("string", {"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"}]}, "email": "user@example.com", "identity": "string", "lookup_key": "string", "metadata": {"key": "value"}, "model": "string", "name": "Example Name", "org": "string", "originator": "string", "phone_number": "+15555550123", "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}, "team": "string", "user": "string"})

JSON body

{
  "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"
      }
    ]
  },
  "email": "user@example.com",
  "identity": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "model": "string",
  "name": "Example Name",
  "org": "string",
  "originator": "string",
  "phone_number": "+15555550123",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "team": "string",
  "user": "string"
}

Response

{
  "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"
}

DELETE/api/v1/agents/{agent}

Delete an agent

Permanently deletes an agent and all of its associated resources. This action cannot be undone. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent to delete.

Responses

204No content
401Unauthorized
403App-scoped token required. Use a token scoped to the target app.; Permission denied. The connected account may not have the required permissions. Try reconnecting your account.
404Agent not found

curl

curl -X DELETE https://developers.archastro.ai/api/v1/agents/{agent} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.agents.delete("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.agents.delete("string")

GET/api/v1/agents/{agent}/agent_computers

List computers

Returns all computers belonging to the authenticated app, ordered by creation time descending. Pass `agent` to scope the results to a single agent's computers. When `agent` is omitted, computers for all agents in the app are returned. Requires an app-scoped API key. If the specified agent does not exist or does not belong to the app, the endpoint returns 404.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`). When provided, only computers belonging to this agent are returned.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_computers \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_computers.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_computers.list("test-value")

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "config": {
        "key": "value"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "error_message": "string",
      "id": "cmp_0aBcDeFgHiJkLmNoPqRsTu",
      "last_active_at": "2024-01-01T00:00:00Z",
      "lookup_key": "main-computer",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "region": "us-east-1",
      "sprite_url": "https://example.com",
      "status": "ready",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/api/v1/agents/{agent}/agent_computers

Provision a computer for an agent

Creates and provisions a new computer resource associated with the specified agent. The computer is allocated in the requested region (defaulting to `iad`) and its status transitions from `provisioning` to `running` once it is ready. Requires an app-scoped API key. The agent identified by `agent` must belong to the same app. Supplying a `lookup_key` lets you retrieve this computer later without storing its ID — the key must be unique within the app.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`). The computer is associated with this agent.

Request body

Name	Type	Description
`config`	object	Provider-specific configuration for the computer. Supported keys vary by region and plan.
`lookup_key`	string	Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID.
`metadata`	object	Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads.
`name`required	string	Human-readable display name for the computer.
`region`	string	Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/agent_computers \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "config": {},
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "region": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_computers.create("test-value", { config: {}, lookup_key: "string", metadata: { key: "value" }, name: "Example Name", region: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_computers.create("test-value", {"config": {}, "lookup_key": "string", "metadata": {"key": "value"}, "name": "Example Name", "region": "string"})

JSON body

{
  "config": {},
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "region": "string"
}

Response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "config": {
    "key": "value"
  },
  "created_at": "2024-01-01T00:00:00Z",
  "error_message": "string",
  "id": "cmp_0aBcDeFgHiJkLmNoPqRsTu",
  "last_active_at": "2024-01-01T00:00:00Z",
  "lookup_key": "main-computer",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "region": "us-east-1",
  "sprite_url": "https://example.com",
  "status": "ready",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET/api/v1/agents/{agent}/agent_env_vars

List an agent's environment variables

Returns all environment variables defined for the specified agent. Variable values are always masked in the response; only the last four characters are visible. To inspect a specific variable, use the retrieve endpoint. The authenticated user must have access to the agent's parent app. Pass the app scope via the `app` parameter when calling with an API key that is scoped to a specific app. Results are returned in an unordered flat list.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`). Returns environment variables belonging to this agent.

Responses

200Successful response
401Unauthorized
403App-scoped token required. Use a token scoped to the target app.; Forbidden
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_env_vars \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_env_vars.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_env_vars.list("test-value")

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "id": "anv_0aBcDeFgHiJkLmNoPqRsTu",
      "key": "OPENAI_API_KEY",
      "masked_value": "****1234",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/api/v1/agents/{agent}/agent_env_vars

Create an agent environment variable

Creates a new environment variable for the specified agent. The variable is stored securely and the plaintext `value` is never returned after creation; subsequent reads return a masked representation showing only the last four characters. The authenticated user must have access to the agent's parent app. Pass the app scope via the `app` parameter when calling with an API key that is scoped to a specific app. Each `key` must be unique within the agent; attempting to create a duplicate key returns a validation error.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`). The agent must belong to an app the caller can access.

Request body

Name	Type	Description
`description`	string	Optional human-readable note describing what the variable is used for.
`key`required	string	Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent.
`value`required	string	Plaintext secret value to store. The value is encrypted at rest and never returned in full.

Responses

200Successful response
401Unauthorized
403App-scoped token required. Use a token scoped to the target app.; Forbidden
404Not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/agent_env_vars \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "description": "An example description.",
  "key": "string",
  "value": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_env_vars.create("test-value", { description: "An example description.", key: "string", value: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_env_vars.create("test-value", {"description": "An example description.", "key": "string", "value": "string"})

JSON body

{
  "description": "An example description.",
  "key": "string",
  "value": "string"
}

Response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "id": "anv_0aBcDeFgHiJkLmNoPqRsTu",
  "key": "OPENAI_API_KEY",
  "masked_value": "****1234",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET/api/v1/agents/{agent}/agent_health_actions

List health actions for an agent

Returns all health actions associated with a given agent. Health actions represent required or recommended steps — such as setting environment variables, completing OAuth installations, or running custom verifiers — that an agent needs to reach a healthy state. Results are not paginated; the full list for the agent is returned. Use the `source`, `status`, and `kind` filters to narrow results to the subset your UI or workflow needs. Multiple values for the same filter are treated as OR (e.g. passing two statuses returns actions matching either). The caller must be authenticated and scoped to the app that owns the agent.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list.
`source`query	array<string>	Filter results to actions from one or more lifecycle stages. Accepted values: `"setup"` (actions created during agent installation) and `"health"` (ongoing health checks). Omit to return actions from all stages.
`status`query	array<string>	Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses.
`kind`query	array<string>	Filter results to actions of one or more kinds. Accepted values: `"env_var"` (a required secret or config value), `"install"` (an OAuth or integration install step), and `"custom"` (a platform-defined check). Omit to return all kinds.

Responses

200Successful response
401Unauthorized
403App-scoped token required. Use a token scoped to the target app.; Forbidden
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_health_actions \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agentHealthActions("string", { source: ["string"], status: ["string"], kind: ["string"] });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_health_actions("string", source=["string"], status=["string"], kind=["string"])

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "depends_on": [
        "string"
      ],
      "description": "An example description.",
      "id": "aha_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "env_var",
      "last_verified_at": "2024-01-01T00:00:00Z",
      "last_verifier_message": "string",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "params": {
        "key": "value"
      },
      "required": true,
      "sort_order": 1,
      "source": "setup",
      "status": "pending",
      "title": "Example Title",
      "updated_at": "2024-01-01T00:00:00Z",
      "verify_config": {}
    }
  ]
}

GET/api/v1/agents/{agent}/agent_installations

List installations for an agent

Returns all installations belonging to the specified agent, across all kinds and states. Use this endpoint to inspect which external services and enablement channels an agent is connected to. Results are scoped to the authenticated app and are returned in an unordered array. To list installations across all agents in an app, use the top-level List Installations endpoint instead. The caller must have app scope for the app that owns the agent.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`) whose installations you want to retrieve.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_installations \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_installations.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_installations.list("test-value")

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "config": {},
      "created_at": "2024-01-01T00:00:00Z",
      "id": "cin_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "enablement/github_app",
      "lookup_key": "string",
      "shared_integration": "int_0aBcDeFgHiJkLmNoPqRsTu",
      "state": "active",
      "status_payload": {},
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/api/v1/agents/{agent}/agent_installations

Create an installation

Creates a new installation for an agent, connecting it to an external service or enablement channel via the specified `kind`. The installation begins in a pending state unless an integration is supplied at creation time, in which case it is activated immediately. Supply `shared_integration` to bind an existing org- or app-level integration, or supply `integration` to create a new integration inline and activate the installation in a single request. Supplying both fields returns 422. Use `lookup_key` to assign a stable identifier you can reference later in knowledge search `source_refs`. The key must be unique within the app, org, and sandbox combination. The caller must have app scope for the app that owns the agent.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`) that will own this installation.

Request body

Name	Type	Description
`config`	object	Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration.
`integration`	object	Inline integration fields to create for `integration/*` kinds. When provided, a new Integration record is created and the installation is activated immediately. Mutually exclusive with `shared_integration`.
`kind`required	string	Installation kind that determines the external service being connected. Examples: `"enablement/github_app"`, `"enablement/slack_bot"`, `"integration/github"`, `"integration/gmail"`, `"web/site"`. Use the List Kinds endpoint to retrieve all supported values.
`lookup_key`	string	Stable identifier you assign to this installation. Propagated to backing context source rows so they can be referenced via knowledge search `source_refs`. Must contain only lowercase letters, numbers, underscores, or hyphens (max 100 characters). Must be unique within the same app, org, and sandbox combination. Omit to skip stable referencing.
`shared_integration`	string	ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/agent_installations \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "config": {},
  "integration": {
    "access_token": "string",
    "installation_id": "string",
    "metadata": {
      "key": "value"
    },
    "refresh_token": "string",
    "workspace_key": "example-slug"
  },
  "kind": "string",
  "lookup_key": "string",
  "shared_integration": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_installations.create("test-value", { config: {}, integration: { access_token: "string", installation_id: "string", metadata: { key: "value" }, refresh_token: "string", workspace_key: "example-slug" }, kind: "string", lookup_key: "string", shared_integration: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_installations.create("test-value", {"config": {}, "integration": {"access_token": "string", "installation_id": "string", "metadata": {"key": "value"}, "refresh_token": "string", "workspace_key": "example-slug"}, "kind": "string", "lookup_key": "string", "shared_integration": "string"})

JSON body

{
  "config": {},
  "integration": {
    "access_token": "string",
    "installation_id": "string",
    "metadata": {
      "key": "value"
    },
    "refresh_token": "string",
    "workspace_key": "example-slug"
  },
  "kind": "string",
  "lookup_key": "string",
  "shared_integration": "string"
}

Response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "config": {},
  "created_at": "2024-01-01T00:00:00Z",
  "id": "cin_0aBcDeFgHiJkLmNoPqRsTu",
  "kind": "enablement/github_app",
  "lookup_key": "string",
  "shared_integration": "int_0aBcDeFgHiJkLmNoPqRsTu",
  "state": "active",
  "status_payload": {},
  "updated_at": "2024-01-01T00:00:00Z"
}

GET/api/v1/agents/{agent}/agent_installations/kinds

List available installation kinds

Returns the full catalogue of installation kinds supported by the platform. Use the returned `kind` values when calling the Create Installation endpoint. The list is platform-wide and does not vary by agent. The `agent` parameter is accepted for future per-agent filtering but is currently unused. The caller must have app scope to call this endpoint.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`). Accepted for forward compatibility but currently does not filter the response.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_installations/kinds \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_installations.kinds("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_installations.kinds("test-value")

Response

{
  "data": [
    {
      "accepts_sources": true,
      "category": "integration",
      "config_schema": {},
      "description": "An example description.",
      "kind": "enablement/github_app",
      "label": "GitHub App",
      "provider": "github",
      "requires_integration": true
    }
  ]
}

POST/api/v1/agents/{agent}/agent_routines

Create a routine

Creates a new routine and attaches it to the specified agent. Routines define how an agent responds to events or a cron schedule; the `handler_type` controls which execution model is used. The routine is created in `"draft"` status by default. To start processing events immediately, either pass `status: "active"` or call the activate endpoint after creation. Scheduled routines must run no more frequently than once per hour. Requires app scope.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`) that this routine will be attached to.

Request body

Name	Type	Description
`acl`	object	Access control list governing who can read or manage this routine.
`config`	string	Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`.
`description`	string	Optional human-readable description of what this routine does.
`event_config`	object	Mapping of event types to trigger configuration. Each key is an event type string; each value is an object with a `"filters"` map and an optional `"dedupe_key_path"` (a JSON path used to deduplicate events, e.g. `"$.thread.id"`).
`event_type`	string	Event type that triggers this routine. Deprecated — use `event_config` instead.
`handler_type`required	string	Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.
`lookup_key`	string	Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app.
`metadata`	object	Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform.
`name`required	string	Human-readable display name for the routine.
`preset_config`	object	Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`.
`preset_name`	string	Name of the registered preset to use. Required when `handler_type` is `"preset"`.
`schedule`	string	Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.
`script`	string	Inline script source. Required when `handler_type` is `"script"`.
`status`	string	Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`.
`steps`	array<object>	Ordered list of steps for a chain handler. Required when `handler_type` is `"chain"`; must be omitted or empty otherwise. Each step must have exactly one handler body field (`preset_name`, `script`, or `config`) matching that step's `handler_type`.
`trigger_context`	string	Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/agent_routines \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "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"
      }
    ]
  },
  "config": "string",
  "description": "An example description.",
  "event_config": {},
  "event_type": "string",
  "handler_type": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "preset_config": {
    "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
    "llm": {
      "model": "claude-sonnet-4-5"
    },
    "session_mode": "stateless",
    "session_scope": "per_user",
    "structured_message_template_ids": [
      "string"
    ]
  },
  "preset_name": "Example Name",
  "schedule": "string",
  "script": "string",
  "status": "string",
  "steps": [
    {
      "config": "string",
      "handler_type": "preset",
      "inputs": {},
      "name": "Example Name",
      "on_error": "halt",
      "output_key": "string",
      "preset_config": {
        "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
        "llm": {
          "model": "claude-sonnet-4-5"
        },
        "session_mode": "stateless",
        "session_scope": "per_user",
        "structured_message_template_ids": [
          "string"
        ]
      },
      "preset_name": "Example Name",
      "script": "string"
    }
  ],
  "trigger_context": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agentRoutines("string", { 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" }] }, config: "string", description: "An example description.", event_config: {}, event_type: "string", handler_type: "string", lookup_key: "string", metadata: { key: "value" }, name: "Example Name", preset_config: { instructions: "You are a helpful assistant. Answer questions concisely and cite sources when possible.", llm: { model: "claude-sonnet-4-5" }, session_mode: "stateless", session_scope: "per_user", structured_message_template_ids: ["string"] }, preset_name: "Example Name", schedule: "string", script: "string", status: "string", steps: [{ config: "string", handler_type: "preset", inputs: {}, name: "Example Name", on_error: "halt", output_key: "string", preset_config: { instructions: "You are a helpful assistant. Answer questions concisely and cite sources when possible.", llm: { model: "claude-sonnet-4-5" }, session_mode: "stateless", session_scope: "per_user", structured_message_template_ids: ["string"] }, preset_name: "Example Name", script: "string" }], trigger_context: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_routines("string", {"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"}]}, "config": "string", "description": "An example description.", "event_config": {}, "event_type": "string", "handler_type": "string", "lookup_key": "string", "metadata": {"key": "value"}, "name": "Example Name", "preset_config": {"instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.", "llm": {"model": "claude-sonnet-4-5"}, "session_mode": "stateless", "session_scope": "per_user", "structured_message_template_ids": ["string"]}, "preset_name": "Example Name", "schedule": "string", "script": "string", "status": "string", "steps": [{"config": "string", "handler_type": "preset", "inputs": {}, "name": "Example Name", "on_error": "halt", "output_key": "string", "preset_config": {"instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.", "llm": {"model": "claude-sonnet-4-5"}, "session_mode": "stateless", "session_scope": "per_user", "structured_message_template_ids": ["string"]}, "preset_name": "Example Name", "script": "string"}], "trigger_context": "string"})

JSON body

{
  "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"
      }
    ]
  },
  "config": "string",
  "description": "An example description.",
  "event_config": {},
  "event_type": "string",
  "handler_type": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "preset_config": {
    "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
    "llm": {
      "model": "claude-sonnet-4-5"
    },
    "session_mode": "stateless",
    "session_scope": "per_user",
    "structured_message_template_ids": [
      "string"
    ]
  },
  "preset_name": "Example Name",
  "schedule": "string",
  "script": "string",
  "status": "string",
  "steps": [
    {
      "config": "string",
      "handler_type": "preset",
      "inputs": {},
      "name": "Example Name",
      "on_error": "halt",
      "output_key": "string",
      "preset_config": {
        "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
        "llm": {
          "model": "claude-sonnet-4-5"
        },
        "session_mode": "stateless",
        "session_scope": "per_user",
        "structured_message_template_ids": [
          "string"
        ]
      },
      "preset_name": "Example Name",
      "script": "string"
    }
  ],
  "trigger_context": "string"
}

Response

{
  "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"
      }
    ]
  },
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "event_config": {},
  "event_type": "agentroutine.invoked",
  "handler_type": "script",
  "id": "arn_0aBcDeFgHiJkLmNoPqRsTu",
  "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "lookup_key": "daily-digest",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "preset_config": {
    "instructions": "You are a helpful assistant. Answer questions concisely and cite sources when possible.",
    "llm": {
      "model": "claude-sonnet-4-5"
    },
    "session_mode": "stateless",
    "session_scope": "per_user",
    "structured_message_template_ids": [
      "string"
    ]
  },
  "preset_name": "Example Name",
  "schedule": "string",
  "script": "string",
  "status": "active",
  "steps": [
    {}
  ],
  "trigger_context": "event",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET/api/v1/agents/{agent}/agent_tools

List agent tools

Returns all tools for the authenticated app, optionally filtered by agent or tool kind. Both explicitly created tools and tools derived from connected integrations (installation-sourced tools) are included in the response. Installation-sourced tools appear with `source: "installation"` and `status: "active"`. They are synthesized at request time from connected integrations and do not have a persistent tool ID of the `atl_...` form; their `id` is a composite of the installation ID and server tool type. Use the `agent` filter to retrieve tools for a specific agent. Supplying an `agent` ID that does not belong to the authenticated app returns 404. Requires app scope.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`kind`query	string	Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds.
`agent`pathrequired	string	Filter results to tools belonging to this agent (`agt_...`). Omit to return tools across all agents in the app.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_tools \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_tools.list("test-value", { kind: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_tools.list("test-value", kind="string")

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "async": true,
      "builtin_tool_config": {},
      "builtin_tool_key": "string",
      "config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "handler_type": "http",
      "id": "atl_0aBcDeFgHiJkLmNoPqRsTu",
      "instruction": "string",
      "kind": "builtin",
      "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "lookup_key": "string",
      "metadata": {
        "key": "value"
      },
      "name": "Example Name",
      "name_prefix": "string",
      "parameters": {},
      "parameters_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "status": "active",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

POST/api/v1/agents/{agent}/agent_tools

Create an agent tool

Creates a new tool and attaches it to the specified agent. Tools can be either `"builtin"` (a platform-provided capability identified by `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, description, parameter schema, and handler). New tools are created in `"draft"` status by default unless `status: "active"` is explicitly supplied. Draft tools are not exposed to the LLM during agent runs; call the activate endpoint to promote them. For built-in tools that support multiple instances per agent (those whose catalog entry has a `multi_instance_mode`), supply `name_prefix` to namespace the LLM-facing tool names. Requires app scope.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`) to attach the tool to.

Request body

Name	Type	Description
`async`	boolean	When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools.
`builtin_tool_config`	object	Configuration object for the built-in tool. Shape is defined by the catalog entry's `config_schema` for the chosen `builtin_tool_key`. Applies only to `"builtin"` tools.
`builtin_tool_key`	string	Key identifying the built-in tool type to add (e.g. `"knowledge_search"`). Required when `kind` is `"builtin"`. Must match a key in the tool catalog.
`config`	string	Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools.
`description`	string	Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools.
`handler_type`	string	Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools.
`kind`required	string	Tool kind. One of `"builtin"` or `"custom"`.
`lookup_key`	string	Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning.
`metadata`	object	Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform.
`name`	string	Display name for the tool. Required when `kind` is `"custom"`.
`name_prefix`	string	Per-instance namespace for built-in tools that support multiple instances per agent. Stamped onto LLM-facing tool names (e.g. `"org"` produces `"org_knowledge_search"`). Must match `^[a-z][a-z0-9_]*$` and be at most 24 characters. Required for `"namespaced"` multi-instance tools; omit for single-instance tools.
`parameters`	object	JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools.
`status`	string	Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/agent_tools \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "async": true,
  "builtin_tool_config": {},
  "builtin_tool_key": "string",
  "config": "string",
  "description": "An example description.",
  "handler_type": "string",
  "kind": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "name_prefix": "string",
  "parameters": {},
  "status": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agent_tools.create("test-value", { async: true, builtin_tool_config: {}, builtin_tool_key: "string", config: "string", description: "An example description.", handler_type: "string", kind: "string", lookup_key: "string", metadata: { key: "value" }, name: "Example Name", name_prefix: "string", parameters: {}, status: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_tools.create("test-value", {"async": True, "builtin_tool_config": {}, "builtin_tool_key": "string", "config": "string", "description": "An example description.", "handler_type": "string", "kind": "string", "lookup_key": "string", "metadata": {"key": "value"}, "name": "Example Name", "name_prefix": "string", "parameters": {}, "status": "string"})

JSON body

{
  "async": true,
  "builtin_tool_config": {},
  "builtin_tool_key": "string",
  "config": "string",
  "description": "An example description.",
  "handler_type": "string",
  "kind": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "name_prefix": "string",
  "parameters": {},
  "status": "string"
}

Response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "async": true,
  "builtin_tool_config": {},
  "builtin_tool_key": "string",
  "config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "handler_type": "http",
  "id": "atl_0aBcDeFgHiJkLmNoPqRsTu",
  "instruction": "string",
  "kind": "builtin",
  "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "name_prefix": "string",
  "parameters": {},
  "parameters_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "status": "active",
  "updated_at": "2024-01-01T00:00:00Z"
}

GET/api/v1/agents/{agent}/agent_working_memory

List working memory entries for an agent

Returns a paginated list of working memory entries belonging to the specified agent. Entries are key-value pairs the agent stores for context between interactions. Results are ordered by creation time descending (newest first) and can be filtered with a substring search against the key name. Requires an app-scoped API key. The authenticated caller must have access to the app the agent belongs to. Returns 403 if the key is not app-scoped, and 404 if the agent does not exist within the accessible scope.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`) whose working memory entries to retrieve.
`page_size`query	integer	Number of entries to return per page. Defaults to 25.
`page`query	integer	Page number to retrieve, starting at 1. Defaults to 1.
`search`query	string	Substring filter applied to entry keys (case-insensitive). Omit to return all keys.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/agent_working_memory \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.agentWorkingMemory("string", { pageSize: 1, page: 1, search: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.agent_working_memory("string", page_size=1, page=1, search="string")

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "expires_at": "2024-01-01T00:00:00Z",
      "id": "amm_0aBcDeFgHiJkLmNoPqRsTu",
      "key": "user_preference",
      "updated_at": "2024-01-01T00:00:00Z",
      "value": "string"
    }
  ],
  "has_next": true,
  "has_prev": true,
  "page": 1,
  "page_size": 20,
  "total_entries": 1,
  "total_pages": 1
}

GET/api/v1/agents/{agent}/export

Export an agent as an AgentTemplate

Reconstructs an AgentTemplate config from a deployed agent and all of its sub-resources (tools, routines, skills, installations). Returns the template definition together with every dependent config file (scripts, workflows, skills, schemas) and their raw content, producing a fully self-contained export bundle. Use this endpoint to snapshot an agent's current configuration for backup, migration, or to seed a new Solution template. Pass `remove_identity: true` to strip instance-specific fields (email, phone number) before export. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent to export.
`remove_identity`query	boolean	When `true`, strips instance-unique identity fields (`email`, `phone_number`) from the exported template so it can be reused as a generic blueprint.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/export \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.export("string", { removeIdentity: true });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.export("string", remove_identity=True)

Response

{
  "configs": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "current_version": {
        "change_description": "An example description.",
        "content_hash": "sha256:2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
        "created_at": "2024-01-01T00:00:00Z",
        "data": {},
        "id": "cfv_0aBcDeFgHiJkLmNoPqRsTu",
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
        "version_number": 1
      },
      "id": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "is_archived": true,
      "kind": "Agent",
      "lookup_key": "string",
      "mime_type": "application/json",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "parent": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "parent_solution": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
      "raw_content": "string",
      "relative_path": "string",
      "sandbox": "string",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
      "virtual_path": "agents/my-agent.yaml"
    }
  ],
  "template": {}
}

GET/api/v1/agents/{agent}/health

Retrieve an agent's health profile

Returns an aggregate health profile for the specified agent, including an overall status, a numeric health score, recent activity metrics, and a list of recommended remediation actions. The health check is computed on demand at request time. The `checked_at` timestamp in the response reflects when the evaluation ran. Use this endpoint to surface diagnostics about tool availability, model configuration, and runtime activity in dashboards or monitoring workflows. The authenticated caller must own the agent or hold sufficient permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent to evaluate.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/health \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.health("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.health("string")

Response

{
  "activity": {},
  "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"
  },
  "checked_at": "2024-01-01T00:00:00Z",
  "checks": [
    {}
  ],
  "counts": {},
  "health_actions": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "depends_on": [
        "string"
      ],
      "description": "An example description.",
      "id": "aha_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "env_var",
      "last_verified_at": "2024-01-01T00:00:00Z",
      "last_verifier_message": "string",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "params": {
        "key": "value"
      },
      "required": true,
      "sort_order": 1,
      "source": "setup",
      "status": "pending",
      "title": "Example Title",
      "updated_at": "2024-01-01T00:00:00Z",
      "verify_config": {}
    }
  ],
  "recent": {},
  "score": 85,
  "status": "ok"
}

GET/api/v1/agents/{agent}/schedules

List schedules for an agent

Returns all schedules belonging to the specified agent in any status. Use the `status` parameter to narrow results to a single lifecycle state. Requires an app-scoped API key. The agent must belong to the app identified by the key.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agi_...`). The agent whose schedules you want to retrieve.
`status`query	string	Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses.

Responses

200Successful response
400Invalid status value
401Unauthorized
403Forbidden - app scope required

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/schedules \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.schedules.list("test-value", { status: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.schedules.list("test-value", status="string")

Response

{
  "data": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "cron_expression": "0 9 * * 1",
      "id": "asc_0aBcDeFgHiJkLmNoPqRsTu",
      "instructions": "Send a daily summary of open support tickets to the team Slack channel.",
      "last_run_at": "2024-01-01T00:00:00Z",
      "max_runs": 10,
      "metadata": {
        "key": "value"
      },
      "next_run_at": "2024-01-01T00:00:00Z",
      "run_count": 1,
      "schedule_type": "recurring",
      "scheduled_at": "2024-01-01T00:00:00Z",
      "status": "active",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "timezone": "America/New_York",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

GET/api/v1/agents/{agent}/schedules/{schedule}

Retrieve a schedule

Returns a single schedule belonging to the specified agent. Use this endpoint to fetch the current state, next run time, and configuration of an individual schedule. Requires an app-scoped API key. Both the agent and the schedule must belong to the app identified by the key. Returns 404 if the schedule does not exist or belongs to a different agent.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agi_...`). The agent that owns the schedule.
`schedule`pathrequired	string	Schedule ID (`asc_...`). The schedule to retrieve.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Schedule not found

curl

curl -X GET https://developers.archastro.ai/api/v1/agents/{agent}/schedules/{schedule} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.schedules.get("test-value", "string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.schedules.get("test-value", "string")

Response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "cron_expression": "0 9 * * 1",
  "id": "asc_0aBcDeFgHiJkLmNoPqRsTu",
  "instructions": "Send a daily summary of open support tickets to the team Slack channel.",
  "last_run_at": "2024-01-01T00:00:00Z",
  "max_runs": 10,
  "metadata": {
    "key": "value"
  },
  "next_run_at": "2024-01-01T00:00:00Z",
  "run_count": 1,
  "schedule_type": "recurring",
  "scheduled_at": "2024-01-01T00:00:00Z",
  "status": "active",
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "timezone": "America/New_York",
  "updated_at": "2024-01-01T00:00:00Z"
}

POST/api/v1/agents/{agent}/search

Search an agent's knowledge base

Performs a semantic search over an agent's knowledge base and returns a ranked, `kind`-discriminated list of matching items. Two item kinds may appear in `data`: - `"chunk"` — chunk-level results from the agent's context store. Present for all agents. - `"document"` — document-level results. Present only when the agent has an active `archastro/knowledge` installation. Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to be comparable across kinds, then merged into a single ranked list. On a relevance tie, chunks appear before documents. The total number of results is capped at `max_results` across both kinds. Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and full-text search; `"vector"` and `"fulltext"` select each strategy independently.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search.

Request body

Name	Type	Description
`max_results`	integer	Maximum total results to return across all kinds. Chunks and documents are ranked together and the list is capped at this value. Defaults to `20`; maximum is `100`.
`mode`	string	Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.
`query`required	string	Natural-language search query used to retrieve relevant knowledge items.
`recency_days`	integer	When set, restricts results to items indexed within the last N days.
`source_types`	array<string>	Array of source-type slugs used to filter chunk results, e.g. `["web", "file"]`. Omit to include all source types.

Responses

200Successful response
401Unauthorized
404Agent not found
422Invalid parameters

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/search \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "max_results": 1,
  "mode": "string",
  "query": "string",
  "recency_days": 1,
  "source_types": [
    "string"
  ]
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.search("string", { max_results: 1, mode: "string", query: "string", recency_days: 1, source_types: ["string"] });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.search("string", {"max_results": 1, "mode": "string", "query": "string", "recency_days": 1, "source_types": ["string"]})

JSON body

{
  "max_results": 1,
  "mode": "string",
  "query": "string",
  "recency_days": 1,
  "source_types": [
    "string"
  ]
}

Response

{
  "data": []
}

POST/api/v1/agents/{agent}/threads

Create a thread for an agent

Creates a new thread owned by the specified agent. The thread is scoped to the agent's identity and is immediately available for messaging. The authenticated caller must have access to the agent's parent app. If your API key is scoped to a specific app, pass that app's ID via the `app` parameter. Attempting to create a thread for an agent you cannot access returns 404. By default the platform may send an automatic welcome message into the new thread. Pass `skip_welcome_message: true` to suppress this behavior.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	Agent ID (`agt_...`). The thread will be owned by this agent.

Request body

Name	Type	Description
`skip_welcome_message`	boolean	When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`.
`thread`required	object	Attributes for the new thread.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Agent not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/threads \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "skip_welcome_message": true,
  "thread": {
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org": "string",
    "settings": {},
    "title": "Example Title"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.threads("string", { skip_welcome_message: true, thread: { description: "An example description.", is_unlisted: true, key: "string", metadata: { key: "value" }, muted: true, org: "string", settings: {}, title: "Example Title" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.threads("string", {"skip_welcome_message": True, "thread": {"description": "An example description.", "is_unlisted": True, "key": "string", "metadata": {"key": "value"}, "muted": True, "org": "string", "settings": {}, "title": "Example Title"}})

JSON body

{
  "skip_welcome_message": true,
  "thread": {
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org": "string",
    "settings": {},
    "title": "Example Title"
  }
}

Response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "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"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "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"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "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"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

POST/api/v1/agents/{agent}/upgrade

Upgrade an agent from an AgentTemplate

Upgrades an existing agent by reconciling it against an AgentTemplate from a Solution. Supports two modes: - `"reapply"` (default) — re-applies the agent's currently tracked template, picking up any changes the template author has made since the last apply. - `"replace"` — moves the agent to a different template. `template` is required in this mode. Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, removes, noops) without writing any changes. The response includes a `review_fingerprint` you can pass back via `expected_review_fingerprint` on the live apply to guard against the diff changing between review and execution. Safe overrides (`name`, `email`, `phone_number`, `metadata`, `identity`, `originator`, `model`) let you pin instance-specific values that should not be overwritten by the template during the upgrade. The authenticated caller must own the agent or hold write permissions within its owning org or team. When called under a developer app scope, the caller must hold the app scope for the target app.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`pathrequired	string	ID (`agi_...`) or `lookup_key` of the agent to upgrade.

Request body

Name	Type	Description
`dry_run`	boolean	When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply.
`email`	string	Instance-specific email address override. Pins this value so the template upgrade does not overwrite it.
`expected_review_fingerprint`	string	Stale-review guard. Pass the `review_fingerprint` returned by a prior `dry_run` response to ensure the diff has not changed between review and live apply. Returns an error if the fingerprint no longer matches.
`identity`	string	Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it.
`metadata`	object	Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it.
`mode`	string	Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`).
`model`	string	Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model.
`name`	string	Instance-specific name override. Pins this value so the template upgrade does not overwrite it.
`originator`	string	Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it.
`phone_number`	string	Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it.
`template`	string	ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode.

Responses

200Successful response
400Bad request
401Unauthorized
403App-scoped token required. Use a token scoped to the target app.; Forbidden
404Agent not found; Template not found
409Agent template changed since review; prepare the diff again.
422Agent has no tracked template; Template has no parent Solution; Config is not an agent template; Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/agents/{agent}/upgrade \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "dry_run": true,
  "email": "user@example.com",
  "expected_review_fingerprint": "string",
  "identity": "string",
  "metadata": {
    "key": "value"
  },
  "mode": "reapply",
  "model": "string",
  "name": "Example Name",
  "originator": "string",
  "phone_number": "+15555550123",
  "template": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.agents.upgrade("string", { dry_run: true, email: "user@example.com", expected_review_fingerprint: "string", identity: "string", metadata: { key: "value" }, mode: "reapply", model: "string", name: "Example Name", originator: "string", phone_number: "+15555550123", template: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.agents.upgrade("string", {"dry_run": True, "email": "user@example.com", "expected_review_fingerprint": "string", "identity": "string", "metadata": {"key": "value"}, "mode": "reapply", "model": "string", "name": "Example Name", "originator": "string", "phone_number": "+15555550123", "template": "string"})

JSON body

{
  "dry_run": true,
  "email": "user@example.com",
  "expected_review_fingerprint": "string",
  "identity": "string",
  "metadata": {
    "key": "value"
  },
  "mode": "reapply",
  "model": "string",
  "name": "Example Name",
  "originator": "string",
  "phone_number": "+15555550123",
  "template": "string"
}

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"
  },
  "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"
  },
  "upgrade_result": {
    "changes": [
      {
        "action": "update",
        "description": "An example description.",
        "field_changes": [
          {
            "field": "name",
            "locally_edited": true
          }
        ],
        "id": "id_0aBcDeFgHiJkLmNoPqRsTu",
        "key": "string",
        "name": "Example Name",
        "parent_template_config": {
          "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"
        },
        "resource": {},
        "resource_type": "tool",
        "source_template_config": {
          "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"
        }
      }
    ],
    "dry_run": true,
    "mode": "full",
    "review_fingerprint": "string",
    "status": "upgraded",
    "summary": {
      "adds": 1,
      "noops": 1,
      "removes": 1,
      "updates": 1
    }
  }
}

/api/v1/auth

Authentication

9 operations

GET/api/v1/auth/allowed_auth_methods

List supported auth methods

Returns the complete catalogue of authentication methods the platform supports, including each method's stable slug, user-facing name, and description. Use this endpoint to render method labels in sign-in UIs or org settings screens without hardcoding copy or maintaining your own enum list. Results reflect the platform's source-of-truth catalogue and are consistent across all orgs. This endpoint requires only a publishable key and is accessible without an active user session, making it suitable for pre-authentication flows such as login page rendering or onboarding configuration.

Publishable key

Responses

200Successful response

curl

curl -X GET https://developers.archastro.ai/api/v1/auth/allowed_auth_methods \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.allowedAuthMethods();

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.allowed_auth_methods()

Response

{
  "data": [
    {
      "description": "An example description.",
      "name": "Example Name",
      "slug": "example-slug"
    }
  ]
}

POST/api/v1/auth/login

Authenticate with email and password

Authenticates a user with an email address and password and returns a short-lived access token, a refresh token, and the authenticated user object. Use the refresh token with the `/auth/refresh` endpoint to obtain new access tokens without re-authenticating. Password login must be enabled for the app; apps that have disabled password authentication return HTTP 403. Requests are rate-limited per IP (10 per minute) and per email-IP pair (5 per minute) — exceeding either limit returns HTTP 429.

Publishable key

Request body

Name	Type	Description
`email`required	string	Email address of the user to authenticate.
`password`required	string	Password for the account associated with the given email.

Responses

200Successful response
401Invalid credentials
403Password login is not enabled for this organization
429Rate limited

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/login \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "email": "user@example.com",
  "password": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.login("test@example.com", "Password1234!");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.login("test@example.com", "Password1234!")

JSON body

{
  "email": "user@example.com",
  "password": "string"
}

Response

{
  "expires_in": 3600,
  "metadata": {
    "key": "value"
  },
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "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"
  }
}

POST/api/v1/auth/login/link

Request a magic link for login

Sends a magic link to the given email address so an existing user can sign in without a password. The user clicks the link in their email and is redirected to `redirect_uri` with a token; pass that token to `/auth/verify_link` to obtain session tokens. If no account exists for the email, the endpoint still returns success to prevent email enumeration — no link is sent in that case. Both `email` and `redirect_uri` are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.

Publishable key

Request body

Name	Type	Description
`email`	string	Email address of the account to send the magic link to.
`redirect_uri`	string	URL the user is redirected to after clicking the magic link. The token is appended as a query parameter.

Responses

204No content
400Missing email or redirect_uri
429Rate limited

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/login/link \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "email": "user@example.com",
  "redirect_uri": "https://example.com"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.requestLoginMagicLink("test@example.com", "https://example.com");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.request_login_magic_link("test@example.com", "https://example.com")

JSON body

{
  "email": "user@example.com",
  "redirect_uri": "https://example.com"
}

POST/api/v1/auth/refresh

Refresh an access token

Exchanges a valid refresh token for a new access token and a new refresh token, rotating the refresh token on every call. The response also includes the updated user object. Store the new refresh token and discard the old one. Refresh tokens are single-use — submitting an already-consumed token returns HTTP 401. Rate limiting is applied per (user, IP) pair when the token can be verified, and falls back to IP-only when it cannot. The limit is 30 exchanges per minute per bucket; exceeding it returns HTTP 429.

Publishable key

Request body

Name	Type	Description
`refresh_token`required	string	Refresh token previously issued by a login, registration, or token-refresh response.

Responses

200Successful response
401Invalid or expired refresh token
429Rate limited

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/refresh \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "refresh_token": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.refresh("test-token");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.refresh("test-token")

JSON body

{
  "refresh_token": "string"
}

Response

{
  "expires_in": 3600,
  "metadata": {
    "key": "value"
  },
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "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"
  }
}

POST/api/v1/auth/register

Register a new user with email and password

Creates a new user account and returns an access token, refresh token, and the new user object. Two registration paths are supported: - **Team registration**: supply `team_invite` with a valid team invite ID. The new user is added to that team immediately upon registration. Returns HTTP 404 if the invite is not found. - **Standard registration**: supply `password`. An `invite_code` may optionally be included for invite-gated apps; an invalid code returns HTTP 404. Exactly one of `team_invite` or `password` must be provided; omitting both returns HTTP 400. Password registration must be enabled for the app; disabled apps return HTTP 403. The response status is HTTP 201 on success.

Publishable key

Request body

Name	Type	Description
`alias`	string	Display alias (handle) for the new account.
`email`required	string	Email address for the new account.
`full_name`	string	Full name for the new account.
`invite_code`	string	Invite code for invite-gated registration. Applied only in the standard registration path.
`password`	string	Password for the new account. Required for standard (non-team-invite) registration.
`team_invite`	string	Team invite ID. When provided, the user is added to the team on registration.
`timezone`	string	IANA timezone name for the new account, e.g. `"America/New_York"`.

Responses

200Successful response
400Missing required parameters
403Password registration is not enabled for this organization
404Team invite not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/register \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "alias": "string",
  "email": "user@example.com",
  "full_name": "Example Name",
  "invite_code": "string",
  "password": "string",
  "team_invite": "string",
  "timezone": "America/New_York"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.register("test@example.com", "test-value", "test-value", "test-value", "Password1234!", "test-value", "UTC");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.register("test@example.com", "test-value", "test-value", "test-value", "Password1234!", "test-value", "UTC")

JSON body

{
  "alias": "string",
  "email": "user@example.com",
  "full_name": "Example Name",
  "invite_code": "string",
  "password": "string",
  "team_invite": "string",
  "timezone": "America/New_York"
}

Response

{
  "expires_in": 3600,
  "metadata": {
    "key": "value"
  },
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "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"
  }
}

POST/api/v1/auth/register/link

Request a magic link for registration

Starts a passwordless registration flow by sending a verification link to the given email address. The recipient clicks the link and is redirected to `redirect_uri` with a token; pass that token to `/auth/verify_link` to complete registration and obtain session tokens. Profile fields (`full_name`, `alias`, `timezone`) are captured now and applied when the link is verified. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute) — exceeding either limit returns HTTP 429. Returns HTTP 204 on success.

Publishable key

Request body

Name	Type	Description
`alias`	string	Display alias (handle) for the new account.
`email`	string	Email address to send the registration magic link to.
`full_name`	string	Full name for the new account.
`redirect_uri`	string	URL the user is redirected to after clicking the registration link. The token is appended as a query parameter.
`timezone`	string	IANA timezone name for the new account, e.g. `"America/New_York"`.

Responses

204No content
400Missing email
422Validation failed
429Rate limited

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/register/link \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "alias": "string",
  "email": "user@example.com",
  "full_name": "Example Name",
  "redirect_uri": "https://example.com",
  "timezone": "America/New_York"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.requestRegisterMagicLink("test-value", "test@example.com", "test-value", "https://example.com", "UTC");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.request_register_magic_link("test-value", "test@example.com", "test-value", "https://example.com", "UTC")

JSON body

{
  "alias": "string",
  "email": "user@example.com",
  "full_name": "Example Name",
  "redirect_uri": "https://example.com",
  "timezone": "America/New_York"
}

POST/api/v1/auth/request/link

Request a magic link for login or registration

Sends a passwordless magic link to the given email address. If an account with that email already exists, a login link is sent. If no account exists, a registration link is sent and the recipient completes sign-up by clicking through. This unified endpoint lets you implement a single email-entry UI that handles both cases transparently. The `redirect_uri` is validated against the app's registered hosts; an unregistered URI returns HTTP 400. Both `email` and `redirect_uri` are required. Requests are rate-limited per IP (10 per minute) and per email-IP pair (3 per minute). Returns HTTP 204 on success — no body.

Publishable key

Request body

Name	Type	Description
`email`	string	Email address to send the magic link to.
`redirect_uri`	string	URL the user is redirected to after clicking the magic link. Must be registered with the app.

Responses

204No content
400Missing email or redirect_uri
422Validation failed
429Rate limited

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/request/link \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "email": "user@example.com",
  "redirect_uri": "https://example.com"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.requestMagicLink("test@example.com", "https://example.com");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.request_magic_link("test@example.com", "https://example.com")

JSON body

{
  "email": "user@example.com",
  "redirect_uri": "https://example.com"
}

POST/api/v1/auth/token

Exchange a one-time login token for session tokens

Consumes a single-use login token delivered via email and returns an access token, refresh token, and the authenticated user object. One-time tokens are issued by the passwordless login flow and expire after a short window; submitting an expired or already-used token returns HTTP 401. If `timezone` is provided and the user's current timezone is still the default (`"America/Los_Angeles"`), the account timezone is updated in the same request. Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.

Publishable key

Request body

Name	Type	Description
`timezone`	string	IANA timezone name to apply to the account if the account timezone is still the default, e.g. `"Europe/London"`. Omit to leave the timezone unchanged.
`token`required	string	Single-use login token extracted from the magic link or email code flow.

Responses

200Successful response
400Missing token
401Invalid or expired token
429Rate limited
500Token exchange failed

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/token \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "timezone": "America/New_York",
  "token": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.exchangeLoginToken("test-token", "UTC");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.exchange_login_token("test-token", "UTC")

JSON body

{
  "timezone": "America/New_York",
  "token": "string"
}

Response

{
  "expires_in": 3600,
  "metadata": {
    "key": "value"
  },
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "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"
  }
}

POST/api/v1/auth/verify/link

Verify a magic link token

Consumes a single-use token from a magic link URL and returns an access token, refresh token, and the authenticated user object. This endpoint completes both the login flow (initiated by `/auth/request_login_link`) and the registration flow (initiated by `/auth/request_register_link` or `/auth/request_link`). Extract the token from the `token` query parameter of the magic link redirect URI and POST it here. Expired or already-used tokens return HTTP 401. If the app has disabled passwordless authentication the request returns HTTP 403. Rate-limited to 10 requests per IP per minute — exceeding this returns HTTP 429.

Publishable key

Request body

Name	Type	Description
`token`	string	Single-use magic link token extracted from the redirect URI query parameter.

Responses

200Successful response
400Missing token
401Invalid or expired token
403Passwordless login is not enabled for this organization
429Rate limited

curl

curl -X POST https://developers.archastro.ai/api/v1/auth/verify/link \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "token": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.auth.verifyMagicLink("test-token");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient(default_headers={"x-archastro-api-key": api_key}) as client:
    result = await client.auth.verify_magic_link("test-token")

JSON body

{
  "token": "string"
}

Response

{
  "expires_in": 3600,
  "metadata": {
    "key": "value"
  },
  "refresh_token": "rt_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDEiLCJleHAiOjE3MTcwMDAwMDB9.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "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"
  }
}

/api/v1/files

Files

2 operations

POST/api/v1/files

Upload a file

Creates a new file from base64-encoded content and returns the resulting file object, including a signed download URL. Use this endpoint to store images, documents, or other binary assets that can then be referenced by agents, teams, or users. App scope is derived from the authenticated viewer's bearer token or publishable key. You may optionally associate the file with an organization, team, user, or agent by passing the corresponding ID. If no owner is specified and the viewer is a user, the file is automatically attributed to that user. Returns `422` when the `data` field is not valid base64 or the changeset is invalid. Returns `403` when the request lacks the required app scope.

Bearer tokenPublishable key

Request body

Name	Type	Description
`agent`	string	Agent ID (`agi_...`) to associate with this file. When provided, the file's organization is derived from the agent.
`content_type`required	string	MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.
`data`required	string	Base64-encoded binary content of the file to upload.
`filename`required	string	Original filename including extension, e.g. `"avatar.png"`.
`org`	string	Organization ID (`org_...`) to associate with this file. Optional; defaults to the viewer's organization when omitted.
`team`	string	Team ID (`tem_...`) that owns this file. Takes precedence over `user` when both are provided.
`user`	string	User ID (`usr_...`) that owns this file. Defaults to the authenticated user when neither `user` nor `team` is specified.

Responses

201Successful response
401Unauthorized
403Forbidden - app scope required
422Validation failed or invalid base64

curl

curl -X POST https://developers.archastro.ai/api/v1/files \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "agent": "string",
  "content_type": "application/json",
  "data": "string",
  "filename": "string",
  "org": "string",
  "team": "string",
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.files.create({ agent: "string", content_type: "application/json", data: "string", filename: "string", org: "string", team: "string", user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.files.create({"agent": "string", "content_type": "application/json", "data": "string", "filename": "string", "org": "string", "team": "string", "user": "string"})

JSON body

{
  "agent": "string",
  "content_type": "application/json",
  "data": "string",
  "filename": "string",
  "org": "string",
  "team": "string",
  "user": "string"
}

Response

{
  "content_type": "application/json",
  "created_at": "2024-01-01T00:00:00Z",
  "filename": "document.pdf",
  "id": "fil_0aBcDeFgHiJkLmNoPqRsTu",
  "image_source": {
    "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
    "height": 600,
    "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
    "mime_type": "application/json",
    "refresh_url": "https://example.com",
    "url": "https://example.com",
    "width": 800
  },
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "size": 1024,
  "updated_at": "2024-01-01T00:00:00Z",
  "url": "https://example.com"
}

GET/api/v1/files/{file}/avatar

Fetch an agent avatar image

Returns the raw image bytes for an agent's profile picture identified by `file`. This endpoint is designed for integration partners (such as Slack) that fetch avatar URLs via plain GET requests without bearer token support. Authorization is performed via a short, stable capability `token` rather than an HTTP header. The `token` is an HMAC-based capability tied to the file ID. It does not expire, but it is invalidated when the agent's profile picture is replaced or the agent is deleted — shared caches may continue serving the old image until the `Cache-Control` max-age of one hour elapses. The endpoint never redirects to a signed storage URL; bytes are served inline so behavior is consistent across storage backends. All failure modes — invalid file ID, invalid token, file not currently referenced as an agent avatar — return a uniform `404` to avoid acting as an existence oracle.

No auth declared

Parameters

Name	Type	Description
`file`pathrequired	string	File ID of the agent's profile picture (`fil_...`). Must be currently set as an agent's profile picture within the same app.
`token`queryrequired	string	HMAC capability token authorizing access to this specific file. Obtained from the avatar URL minted when the profile picture was set.

Responses

200Raw image bytes of the agent avatar, served with the file's original content type.
404Not found

curl

curl -X GET https://developers.archastro.ai/api/v1/files/{file}/avatar

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.files.avatar("string", { token: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.files.avatar("string", token="string")

/oauth

OAuth

5 operations

POST/oauth/device/approve

Approve a device authorization request

Grants the pending device authorization identified by `user_code`, completing the OAuth Device Authorization flow on behalf of the authenticated user. Once approved, the device can exchange the `device_code` for an access token. Requires a valid user session — the request must be authenticated as an end user, not a machine client. The `user_code` must belong to a pending (not expired, not already approved or denied) authorization associated with the calling app. If the requested scopes include a `thread`-scoped permission, you must supply the `thread` parameter; omitting it returns a 400 with `error: "invalid_scope"`.

No auth declared

Request body

Name	Type	Description
`thread`	string	Thread ID (`thr_...`) to bind to the authorization. Required when the requested scopes include a thread-scoped permission.
`user_code`required	string	User-facing verification code shown on the device. Identifies the pending authorization to approve.

Responses

200Successful response
400Bad request
401Unauthorized

curl

curl -X POST https://developers.archastro.ai/oauth/device/approve \
  -H "content-type: application/json" \
  -d '{
  "thread": "string",
  "user_code": "string"
}'

JSON body

{
  "thread": "string",
  "user_code": "string"
}

Response

{
  "status": "approved"
}

POST/oauth/device/authorize

Initiate a device authorization request

Starts the OAuth 2.0 Device Authorization flow for a device that cannot perform browser-based redirects. Returns a `device_code` (used by the device to poll for a token) and a `user_code` (shown to the user to enter at the `verification_uri`). This endpoint requires a publishable API key; secret keys are rejected with a 403. Third-party OAuth must be enabled on the app; if it is not, the response returns `error: "third_party_oauth_not_enabled"` with a 403. The endpoint is rate-limited to 10 requests per IP per minute. Excess requests receive a 429 response. The returned codes expire after `expires_in` seconds; once expired, a new authorization request must be initiated.

No auth declared

Request body

Name	Type	Description
`client`required	string	OAuth client ID (`cli_...`) identifying the application requesting authorization.
`scope`	string	Space-separated list of OAuth scopes to request, e.g. `"read write"`. Omit to request only the default scopes configured for the client.

Responses

200Successful response
400Bad request
403Forbidden
429Rate limited

curl

curl -X POST https://developers.archastro.ai/oauth/device/authorize \
  -H "content-type: application/json" \
  -d '{
  "client": "string",
  "scope": "string"
}'

JSON body

{
  "client": "string",
  "scope": "string"
}

Response

{
  "device_code": "string",
  "expires_in": 1800,
  "interval": 5,
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com",
  "verification_uri_complete": "string"
}

POST/oauth/device/deny

Deny a device authorization request

Rejects the pending device authorization identified by `user_code`, preventing the device from obtaining an access token. Once denied, the device will receive an `access_denied` error on its next token poll. Requires a valid user session. The `user_code` must belong to a pending authorization associated with the calling app. Attempting to deny an already approved, already denied, or expired authorization returns a 400.

No auth declared

Request body

Name	Type	Description
`user_code`required	string	User-facing verification code shown on the device. Identifies the pending authorization to deny.

Responses

200Successful response
400Bad request
401Unauthorized

curl

curl -X POST https://developers.archastro.ai/oauth/device/deny \
  -H "content-type: application/json" \
  -d '{
  "user_code": "string"
}'

JSON body

{
  "user_code": "string"
}

Response

{
  "status": "approved"
}

GET/oauth/scopes

List available OAuth scopes

Returns the complete set of OAuth scopes that the platform supports. Use this endpoint to discover which scopes are available before constructing an authorization request or rendering a consent UI. No authentication is required. The response is the same for all callers.

No auth declared

Responses

200Successful response

POST/oauth/token

Exchange a grant for OAuth tokens

Issues an access token and a refresh token in exchange for a valid grant. Three grant types are supported: `"authorization_code"`, `"refresh_token"`, and `"urn:ietf:params:oauth:grant-type:device_code"`. For `"authorization_code"` grants, supply `code`, `client`, `redirect_uri`, and optionally `code_verifier` for PKCE flows. Each authorization code is single-use; consuming it a second time returns `invalid_grant`. For `"refresh_token"` grants, supply `refresh_token`. The endpoint rotates the refresh token on every call and returns a fresh pair of tokens. For device-code grants, supply `device_code` and `client`. Poll this endpoint after receiving `authorization_pending` until the user approves or the code expires. Slow down polling if you receive `slow_down`. This endpoint is rate-limited to 20 requests per IP per 60 seconds. Exceeding the limit returns HTTP 429 with `"error": "too_many_requests"`.

No auth declared

Request body

Name	Type	Description
`client`	string	OAuth client ID identifying the application requesting tokens. Required for `"authorization_code"` and device-code grants.
`code`	string	Single-use authorization code issued by the authorization endpoint. Required for `"authorization_code"` grants.
`code_verifier`	string	PKCE code verifier corresponding to the `code_challenge` sent in the authorization request. Required when the authorization code was issued with a code challenge; omit otherwise.
`device_code`	string	Device code received from the device authorization endpoint. Required for device-code grants.
`grant_type`required	string	The OAuth 2.0 grant type. One of `"authorization_code"`, `"refresh_token"`, or `"urn:ietf:params:oauth:grant-type:device_code"`.
`redirect_uri`	string	Redirect URI that was used in the original authorization request. Must exactly match the URI on record for the client. Required for `"authorization_code"` grants.
`refresh_token`	string	Refresh token received from a previous token response. Required for `"refresh_token"` grants. The token is rotated on each successful call.

Responses

200Successful response
400Bad request
401Unauthorized
429Rate limited

curl

curl -X POST https://developers.archastro.ai/oauth/token \
  -H "content-type: application/json" \
  -d '{
  "client": "string",
  "code": "string",
  "code_verifier": "string",
  "device_code": "string",
  "grant_type": "string",
  "redirect_uri": "https://example.com",
  "refresh_token": "string"
}'

JSON body

{
  "client": "string",
  "code": "string",
  "code_verifier": "string",
  "device_code": "string",
  "grant_type": "string",
  "redirect_uri": "https://example.com",
  "refresh_token": "string"
}

Response

{
  "access_token": "string",
  "expires_in": 3600,
  "refresh_token": "string",
  "scope": "read write",
  "token_type": "Bearer",
  "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"
  }
}

/api/v1/slack_channel_bindings

Slack Channel Bindings

4 operations

GET/api/v1/slack_channel_bindings

List Slack channel bindings

Returns a page of Slack channel bindings visible to the authenticated user. Results can be filtered by integration, team, agent, or organization. Omit all filter params to retrieve every binding the caller can see. Pagination is page-based. Pass `page` and `per_page` to navigate large result sets. `page` must be a positive integer; `per_page` must be between 1 and 100. Invalid values return 400.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`per_page`query	integer	Number of bindings to return per page. Defaults to 25; maximum is 100.
`page`query	integer	Page number to retrieve, 1-indexed. Defaults to 1. Must be a positive integer.
`team`query	array<string>	Return only bindings bound to one of these team IDs. Omit to return bindings for all teams.
`org`query	array<string>	Return only bindings that belong to one of these organization IDs. Omit to return bindings across all organizations visible to the caller.
`agent`query	array<string>	Return only bindings that have at least one of these agent user IDs attached. Omit to return bindings regardless of agent attachment.
`integration`query	array<string>	Return only bindings whose Slack integration matches one of these integration IDs. Omit to return bindings across all integrations.

Responses

200Successful response
400Bad request
401Unauthorized
403Forbidden

curl

curl -X GET https://developers.archastro.ai/api/v1/slack_channel_bindings \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.slack_channel_bindings.list({ perPage: 1, page: 1, team: ["string"], org: ["string"], agent: ["string"], integration: ["string"] });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.slack_channel_bindings.list(per_page=1, page=1, team=["string"], org=["string"], agent=["string"], integration=["string"])

Response

{
  "data": [
    {
      "agents": [
        "string"
      ],
      "channel": "C01234ABCDE",
      "customer_label": "string",
      "id": "string",
      "integration": "string",
      "is_ext_shared_cached": true,
      "team": "string"
    }
  ],
  "page": 1,
  "per_page": 20,
  "total_count": 1,
  "total_pages": 1
}

POST/api/v1/slack_channel_bindings

Create or update a Slack channel binding

Creates a new binding between a Slack channel and a team, or updates the existing binding if one already exists for the given channel. The caller also supplies a list of agents to attach to the binding and enroll as members of the destination team. The caller must have team-manage rights on the destination team (and on the currently bound team if the channel is being re-pointed). Returns 403 if permission is insufficient. All write steps are idempotent, so retrying after a partial failure is safe. On success the REST endpoint returns 201 Created. The script binding (`slack.channel_bindings.upsert`) returns the full binding object including the attached agents.

Bearer tokenPublishable key

Request body

Name	Type	Description
`agent_user_ids`required	array<string>	List of agent user IDs to attach to the binding and enroll as members of the destination team. Pass an empty array to bind the channel without attaching any agents.
`channel_id`required	string	Slack channel ID to bind (e.g. `C01234ABCDE`). Acts as the natural key of the binding within the workspace.
`customer_label`	string	Human-readable label for the customer associated with this channel. Stored in the binding's config. `null` if omitted.
`is_ext_shared_cached`	boolean	Cached value of Slack's `is_ext_shared` flag for the channel. When provided, this value is persisted on the binding to avoid repeated Slack API lookups. `null` if omitted.
`slack_team_id`required	string	Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Identifies which Slack integration to use.
`team_id`required	string	ID of the team to bind the Slack channel to. The caller must have team-manage rights on this team.

Responses

200Successful response
400Bad request
401Unauthorized
403Forbidden; The Slack integration referenced by this binding is not visible to the caller
404Agent not found; Team not found
422Invalid parameters; Binding org_id does not match the integration's org_id

curl

curl -X POST https://developers.archastro.ai/api/v1/slack_channel_bindings \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "agent_user_ids": [
    "string"
  ],
  "channel_id": "string",
  "customer_label": "string",
  "is_ext_shared_cached": true,
  "slack_team_id": "string",
  "team_id": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.slack_channel_bindings.create({ agent_user_ids: ["string"], channel_id: "string", customer_label: "string", is_ext_shared_cached: true, slack_team_id: "string", team_id: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.slack_channel_bindings.create({"agent_user_ids": ["string"], "channel_id": "string", "customer_label": "string", "is_ext_shared_cached": True, "slack_team_id": "string", "team_id": "string"})

JSON body

{
  "agent_user_ids": [
    "string"
  ],
  "channel_id": "string",
  "customer_label": "string",
  "is_ext_shared_cached": true,
  "slack_team_id": "string",
  "team_id": "string"
}

Response

{
  "agents": [
    "string"
  ],
  "channel": "C01234ABCDE",
  "customer_label": "string",
  "id": "string",
  "integration": "string",
  "is_ext_shared_cached": true,
  "team": "string"
}

GET/api/v1/slack_channel_bindings/{channel}

Retrieve a Slack channel binding

Returns the Slack channel binding identified by a Slack channel ID and workspace team ID pair. Use this endpoint to look up the team and agents currently bound to a specific Slack channel. The `channel` path parameter is the Slack channel ID; `slack_team_id` identifies the Slack workspace the channel belongs to, disambiguating channels with the same ID across workspaces. Both parameters are required. Returns 404 if no binding exists for the given pair or the associated Slack integration is not visible to the caller.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`channel`pathrequired	string	Slack channel ID of the binding to retrieve (e.g. `C01234ABCDE`).
`slack_team_id`queryrequired	string	Slack workspace team ID that the channel belongs to (e.g. `T01234ABCDE`). Used together with `channel` to uniquely identify the binding.

Responses

200Successful response
400Bad request
401Unauthorized
403The Slack integration referenced by this binding is not visible to the caller
404Slack channel binding not found
422Invalid parameters

curl

curl -X GET https://developers.archastro.ai/api/v1/slack_channel_bindings/{channel} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.slack_channel_bindings.get("string", { slackTeamId: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.slack_channel_bindings.get("string", slack_team_id="string")

Response

{
  "agents": [
    "string"
  ],
  "channel": "C01234ABCDE",
  "customer_label": "string",
  "id": "string",
  "integration": "string",
  "is_ext_shared_cached": true,
  "team": "string"
}

DELETE/api/v1/slack_channel_bindings/{channel}

Delete a Slack channel binding

Removes the binding between a Slack channel and its associated team. The channel is identified by its Slack channel ID together with the `slack_team_id` that scopes it to a specific Slack workspace. Removing the binding does not delete the bound team or any conversation threads scoped to it; decommission those resources separately if required. The caller must have team-manage rights on the team the channel is currently bound to. Returning 403 indicates insufficient permission; returning 404 indicates the binding does not exist or is not visible to the caller. The REST endpoint returns 204 No Content on success. The script binding (`slack.channel_bindings.delete`) returns a confirmation object so script callers can verify success without an additional fetch. Both paths are idempotent — retrying after a partial failure is safe.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`channel`pathrequired	string	Slack channel ID of the binding to delete (e.g. `C01234ABCDE`).

Responses

200Successful response
400Bad request
401Unauthorized
403Forbidden; The Slack integration referenced by this binding is not visible to the caller
404Slack channel binding not found
422Invalid parameters

curl

curl -X DELETE https://developers.archastro.ai/api/v1/slack_channel_bindings/{channel} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.slack_channel_bindings.delete("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.slack_channel_bindings.delete("string")

Response

{
  "channel": "string",
  "deleted": true
}

/api/v1/teams

Teams

20 operations

GET/api/v1/teams

List teams

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.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`membership`query	string	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.
`search`query	string	Full-text search string matched against team name and description.
`page_size`query	integer	Number of teams to return per page. Defaults to 25.
`page`query	integer	Page number to retrieve, starting at 1. Defaults to 1.
`metadata`query	object	Structured metadata filter expression. Only teams whose metadata satisfies the expression are returned.

Responses

200Successful response
400Bad request - invalid metadata filter
401Unauthorized
403Forbidden - app scope required

curl

curl -X GET https://developers.archastro.ai/api/v1/teams \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.list({ membership: "string", search: "string", pageSize: 1, page: 1, metadata: {} });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.list(membership="string", search="string", page_size=1, page=1, metadata={})

Response

{
  "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
}

POST/api/v1/teams

Create a team

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.

Bearer tokenPublishable key

Request body

Name	Type	Description
`acl`	object	Access control configuration for the team. Controls who can discover and join the team.
`description`	string	Optional human-readable description of the team's purpose.
`metadata`	object	Arbitrary key-value pairs you can attach to the team for your own use. Values must be strings.
`name`required	string	Display name for the team.
`org`	string	Organization ID (`org_...`) to associate the team with. Omit to create the team without an org affiliation.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/teams \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "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"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.create({ 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" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.create({"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"})

JSON body

{
  "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"
}

Response

{
  "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"
}

GET/api/v1/teams/{team}

Retrieve a team

Returns the full team object for the given `team` ID, including its current member list and all associated threads. The authenticated user must be a member of the team or hold a role that grants visibility (org admin, app scope). When `app` is supplied, the caller must hold the corresponding app scope.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`) of the team to retrieve.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Team not found

curl

curl -X GET https://developers.archastro.ai/api/v1/teams/{team} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.get("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.get("string")

Response

{
  "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"
}

PATCH/api/v1/teams/{team}

Update a team

Updates one or more attributes of the team identified by `team`. Only the fields you provide are changed; omitted fields are left as-is. To replace the team's profile picture, supply the `profile_picture` object with base64-encoded image data. The previous picture is deleted after the new one is successfully uploaded. When `app` is present, the caller must hold the corresponding app scope. The caller must be a team owner or org admin.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`) of the team to update.

Request body

Name	Type	Description
`acl`	object	New access control configuration for the team. Replaces the existing ACL.
`description`	string	New human-readable description of the team's purpose.
`metadata`	object	Arbitrary key-value pairs to set on the team. Replaces the existing metadata map entirely.
`name`	string	New display name for the team.
`profile_picture`	object	New profile picture for the team. Provide this object to upload and replace the current picture.

Responses

200Successful response
401Unauthorized
403Forbidden - app scope required
404Team not found
422Validation failed

curl

curl -X PATCH https://developers.archastro.ai/api/v1/teams/{team} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "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",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.update("string", { 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", profile_picture: { data: "string", filename: "string", mime_type: "application/json" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.update("string", {"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", "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}})

JSON body

{
  "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",
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  }
}

Response

{
  "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"
}

DELETE/api/v1/teams/{team}

Delete a team

Permanently deletes the team identified by `team`. This action is irreversible — all team memberships, settings, and associated data are removed. The caller must be the team owner or an org admin. When `app` is present, the caller must also hold the corresponding app scope.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`) of the team to delete.

Responses

204No content
401Unauthorized
403Forbidden - app scope required
404Team not found

curl

curl -X DELETE https://developers.archastro.ai/api/v1/teams/{team} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.teams.delete("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.teams.delete("string")

GET/api/v1/teams/{team}/artifacts

List a team's artifacts

Returns all artifacts owned by the specified team. Artifacts represent AI-generated or user-uploaded files associated with agent sessions, threads, or sandboxes — such as images, documents, and code outputs. The authenticated user must be a member of the team. Attempting to list artifacts for a team the caller does not have access to returns 404 rather than 403 to avoid leaking team existence. Results are returned in a single page without cursor pagination. Each artifact in the response reflects the state of its current version, including a short-lived signed `file_url` for direct download.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`tea_...`). The authenticated user must be a member of this team.

Responses

200Successful response
401Unauthorized
404Team not found

curl

curl -X GET https://developers.archastro.ai/api/v1/teams/{team}/artifacts \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.artifacts.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.artifacts.list("test-value")

Response

{
  "data": [
    {
      "agent": "agt_0aBcDeFgHiJkLmNoPqRsTu",
      "content_type": "application/json",
      "created_at": "2024-01-01T00:00:00Z",
      "current_version": "afv_0aBcDeFgHiJkLmNoPqRsTu",
      "description": "An example description.",
      "file": "string",
      "file_name": "Example Name",
      "file_url": "https://example.com",
      "id": "art_0aBcDeFgHiJkLmNoPqRsTu",
      "image_source": {
        "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
        "height": 600,
        "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
        "mime_type": "application/json",
        "refresh_url": "https://example.com",
        "url": "https://example.com",
        "width": 800
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox": "string",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
      "version": 1
    }
  ]
}

POST/api/v1/teams/{team}/artifacts

Create an artifact

Creates a new artifact and stores its file content. A file payload is required; supply it via the `artifact.file_content` (Base64-encoded), `artifact.file_name`, and `artifact.file_content_type` fields. The artifact is scoped to the owner resolved from the request context — either a team or a user. Optionally associate the artifact with an existing thread or agent by passing `artifact.thread_id` or `artifact.agent_id`. Returns 201 with the created artifact on success.

Bearer tokenPublishable key

Request body

Name	Type	Description
`artifact`required	object	Object containing the attributes for the new artifact.

Responses

200Successful response
401Unauthorized
403Forbidden
422Validation error

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/artifacts \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "artifact": {}
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.artifacts.create("test-value", { artifact: {} });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.artifacts.create("test-value", {"artifact": {}})

JSON body

{
  "artifact": {}
}

Response

{
  "agent": "agt_0aBcDeFgHiJkLmNoPqRsTu",
  "content_type": "application/json",
  "created_at": "2024-01-01T00:00:00Z",
  "current_version": "afv_0aBcDeFgHiJkLmNoPqRsTu",
  "description": "An example description.",
  "file": "string",
  "file_name": "Example Name",
  "file_url": "https://example.com",
  "id": "art_0aBcDeFgHiJkLmNoPqRsTu",
  "image_source": {
    "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
    "height": 600,
    "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
    "mime_type": "application/json",
    "refresh_url": "https://example.com",
    "url": "https://example.com",
    "width": 800
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "string",
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
  "version": 1
}

GET/api/v1/teams/{team}/custom_objects

List a team's custom objects

Returns a paginated list of custom objects owned by the specified team, filtered to a single schema type. Results are ordered by creation time descending unless `query` is provided, in which case they are ordered by full-text relevance score descending. Use `limit` and `offset` for page-based pagination. Use `row_key` or `sort_key` to narrow results to objects matching those index values. Full-text search via `query` operates only against the fields configured as `search_fields` on the schema. The authenticated user must be a member of the team with sufficient access. Returns 404 if the team is not found, the caller lacks access, or `type` does not match a registered schema for the team's organization.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`row_key`query	string	Filter results to objects whose `row_key` exactly matches this value.
`sort_key`query	string	Filter results to objects whose `sort_key` exactly matches this value.
`query`query	string	Full-text search string matched against the schema's configured `search_fields`. When provided, results are ordered by relevance score descending instead of creation time descending.
`limit`query	integer	Maximum number of objects to return per page.
`offset`query	integer	Number of objects to skip before returning results. Use with `limit` for page-based pagination.
`type`queryrequired	string	Schema type identifier (`lookup_key`) that filters results to objects of this schema.
`team`pathrequired	string	Team ID (`team_...`). Scopes results to objects owned by this team.

Responses

200Successful response
401Unauthorized
404Team not found or schema type not found

curl

curl -X GET https://developers.archastro.ai/api/v1/teams/{team}/custom_objects \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.custom_objects.list("test-value", { rowKey: "string", sortKey: "string", query: "string", limit: 1, offset: 1, type: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.custom_objects.list("test-value", row_key="string", sort_key="string", query="string", limit=1, offset=1, type="string")

Response

{
  "data": [
    {
      "created_at": "2024-01-01T00:00:00Z",
      "fields": {
        "key": "value"
      },
      "id": "cobj_0aBcDeFgHiJkLmNoPqRsTu",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "row_key": "string",
      "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
      "schema_type": "contact",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
      "version": 1
    }
  ],
  "meta": {}
}

POST/api/v1/teams/{team}/custom_objects

Create a team custom object

Creates a new custom object owned by the specified team. The object is instantiated against the schema identified by `type` (the schema's `lookup_key`). All field values are validated against that schema's field definitions before the object is persisted. The authenticated user must be a member of the team with sufficient access. If the team is not found or the caller lacks access, the endpoint returns 404. If `type` does not match a registered schema for the team's organization, the endpoint also returns 404.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`). The team that will own the created object.

Request body

Name	Type	Description
`fields`required	object	Map of field values to set on the new object. Keys and value types must conform to the schema identified by `type`.
`type`required	string	Schema type identifier (`lookup_key`) that defines the object's fields and validation rules.

Responses

200Successful response
401Unauthorized
404Team not found or schema type not found
422Validation error

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/custom_objects \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "fields": {},
  "type": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.custom_objects.create("test-value", { fields: {}, type: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.custom_objects.create("test-value", {"fields": {}, "type": "string"})

JSON body

{
  "fields": {},
  "type": "string"
}

Response

{
  "created_at": "2024-01-01T00:00:00Z",
  "fields": {
    "key": "value"
  },
  "id": "cobj_0aBcDeFgHiJkLmNoPqRsTu",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "row_key": "string",
  "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
  "schema_type": "contact",
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
  "version": 1
}

POST/api/v1/teams/{team}/invite

Create a team invite

Generates a new invite code for the specified team. The authenticated user must be a member of the team with the `owner` or `admin` role. The returned code is a short alphanumeric string that other users can present to join the team. Each call produces a new code; previously issued codes are not invalidated by this request.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`tm_...`) identifying the team for which to generate the invite code.

Responses

200Successful response
401Unauthorized
403Forbidden
404Team not found

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/invite \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.invite("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.invite("string")

Response

{
  "code": "XKCD42"
}

POST/api/v1/teams/{team}/invites

Create a team invite (server-to-server)

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.

Secret key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`tm_...`) identifying the team for which to generate the invite code.

Responses

200Successful response
401Unauthorized
404Team not found

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/invites \
  -H "x-archastro-api-key: $ARCHASTRO_SECRET_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.invites("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.invites("string")

Response

{
  "code": "string"
}

POST/api/v1/teams/{team}/join

Join a team

Adds a principal to a team that is visible to the authenticated user. By default, the currently authenticated user joins the team. Provide `agent` to add an agent to the team instead — the caller must already be a member of the team to do so. Provide `user` (by ID) or `email` to add another user from your organization — the caller must be a team owner, team admin, or org admin. Only one of `agent`, `user`, or `email` may be supplied per request. If the target principal is already a member of the team, the request succeeds without creating a duplicate membership. Server-to-server callers are not permitted to use this endpoint; use the invite-code endpoint instead.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`) to join.

Request body

Name	Type	Description
`agent`	string	Agent ID (`agent_...`) to add to the team. The caller must already be a member of the team.
`email`	string	Email address of a member of the caller's organization to add to the team. Requires team-owner, team-admin, or org-admin role.
`user`	string	User ID (`user_...`) of a member of the caller's organization to add to the team. Requires team-owner, team-admin, or org-admin role.

Responses

204No content
400Bad request
401Unauthorized
403Forbidden
404Not found

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/join \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "agent": "string",
  "email": "user@example.com",
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.teams.join("string", { agent: "string", email: "user@example.com", user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.teams.join("string", {"agent": "string", "email": "user@example.com", "user": "string"})

JSON body

{
  "agent": "string",
  "email": "user@example.com",
  "user": "string"
}

DELETE/api/v1/teams/{team}/leave

Leave a team

Removes a principal from a team. By default, the authenticated user removes themselves from the team. Provide `agent` to remove an agent instead — the caller must be a member of the team to do so. Team owners cannot leave their own team. To transfer ownership first, use the update-membership endpoint, then call this endpoint. For server-to-server requests, `user` is required to identify which user should be removed.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`) to leave.

Responses

204No content
401Unauthorized
403Forbidden
404Not a member of this team
422Failed to leave team

curl

curl -X DELETE https://developers.archastro.ai/api/v1/teams/{team}/leave \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.teams.leave("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.teams.leave("string")

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

List members of a team

Returns all members of the specified team, including both users and agents. Members are returned in a single non-paginated array ordered by join time. Bearer-authenticated users must be a member of the team to retrieve its member list. Developer and server-to-server callers can retrieve members for any team visible to their app scope. When `app` is provided, the request is scoped to that app and requires a valid app-scoped token.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`). The team whose members you want to list.

Responses

200Successful response
401Unauthorized
404Team not found

curl

curl -X GET https://developers.archastro.ai/api/v1/teams/{team}/members \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.members.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.members.list("test-value")

Response

{
  "data": [
    {
      "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"
      }
    }
  ]
}

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

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.

Secret key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`). The team to add the member to.

Request body

Name	Type	Description
`agent`	string	Agent ID (`agt_...`) to add as a member. Provide exactly one of `user` or `agent`.
`role`	string	Role to assign. One of `"owner"`, `"admin"`, or `"member"`. Defaults to `"member"` when omitted.
`user`	string	User ID (`usr_...`) to add as a member. Provide exactly one of `user` or `agent`.

Responses

200Successful response
401Unauthorized
404Team or member not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/members \
  -H "x-archastro-api-key: $ARCHASTRO_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
  "agent": "string",
  "role": "string",
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.members.create("test-value", { agent: "string", role: "string", user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.members.create("test-value", {"agent": "string", "role": "string", "user": "string"})

JSON body

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

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"
  }
}

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

Remove a member or org from a team

Removes a user, agent, or all members of an organization from the specified team. Provide exactly one of `user`, `agent`, or `org` — supplying more than one or none returns a 400 error. On success, returns 204 No Content. When `org` is provided, every user and agent membership belonging to that org is removed in a single call. The caller must be a member of the team's owning org to perform an org-scoped removal. You cannot target the team's owning org itself with this parameter. The caller must have permission to manage the team. When `app` is present, the request is scoped to that app and requires a valid app-scoped token.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`). The team to remove the member from.

Responses

204No content
400Provide exactly one of user, agent, or org
401Unauthorized
403Forbidden
404Team or member not found

curl

curl -X DELETE https://developers.archastro.ai/api/v1/teams/{team}/members \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.teams.members.remove("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.teams.members.remove("test-value")

PATCH/api/v1/teams/{team}/members/{user}

Update a team member's role

Changes the role of an existing user member on the specified team. Returns the updated membership on success. Only user memberships are supported by this endpoint. Attempting to update an agent membership returns 404. To change an agent's role, remove the existing membership and re-add the agent with the desired role. The caller must have permission to modify the team. You cannot change a member's role across organization boundaries. Demoting the last owner of a team returns 409. An invalid `role` value returns 422. When `app` is provided, the request is scoped to that app and requires a valid app-scoped token.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`team_...`). The team whose member role you want to update.
`user`pathrequired	string	User ID (`usr_...`) of the existing member whose role should be changed.

Request body

Name	Type	Description
`role`required	string	New role to assign. One of `"owner"`, `"admin"`, or `"member"`.

Responses

200Successful response
401Unauthorized
403Forbidden — caller lacks permission to modify this team
404Team or member not found
409Conflict — cannot demote the last owner
422Validation failed (e.g. invalid role)

curl

curl -X PATCH https://developers.archastro.ai/api/v1/teams/{team}/members/{user} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "role": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.members.update("test-value", "string", { role: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.members.update("test-value", "string", {"role": "string"})

JSON body

{
  "role": "string"
}

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"
  }
}

GET/api/v1/teams/{team}/threads

List threads for a team

Returns all threads owned by the specified team that the authenticated caller has permission to view. The caller must have access to the team; requests without team access are rejected with 404. Threads are returned in a single `data` array. Use the team-scoped thread endpoints to create, update, or delete individual threads.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`tem_...`) whose threads should be listed.

Responses

200Successful response
401Unauthorized
404Team not found

curl

curl -X GET https://developers.archastro.ai/api/v1/teams/{team}/threads \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.threads.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.threads.list("test-value")

Response

{
  "data": [
    {
      "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "creator": {
        "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"
      },
      "description": "An example description.",
      "id": "string",
      "is_channel": true,
      "is_default": true,
      "is_transient": true,
      "is_unlisted": true,
      "key": "string",
      "last_activity": "2024-01-01T00:00:00Z",
      "metadata": {
        "key": "value"
      },
      "muted": true,
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "parent_message": {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      },
      "participant": [
        "string"
      ],
      "participants": [
        {
          "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"
        }
      ],
      "participating_actor": [
        "string"
      ],
      "participating_agents": [
        {
          "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"
        }
      ],
      "role": "member",
      "sandbox": "string",
      "settings": {
        "agent_enabled": true
      },
      "slug": "example-slug",
      "sub_threads": [
        {}
      ],
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "title": "Example Title",
      "ttl": 3600,
      "unread_count": 5,
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  ]
}

POST/api/v1/teams/{team}/threads

Create a thread for a team

Creates a new thread owned by the specified team. The authenticated caller must have access to the team; requests from callers without team access are rejected with 404. If a `profile_picture` is provided in the thread params, it must be base64-encoded image data. The image is uploaded and associated with the thread before creation completes. Omit `profile_picture` to skip this step. By default the platform sends an automatic welcome message into the new thread. Pass `skip_welcome_message: true` to suppress this behavior, for example when creating threads programmatically in bulk or seeding test data.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`team`pathrequired	string	Team ID (`tem_...`) that will own the created thread.

Request body

Name	Type	Description
`skip_welcome_message`	boolean	When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`.
`thread`required	object	Attributes for the new thread. See ThreadCreateParams for available fields.

Responses

200Successful response
401Unauthorized
404Team not found
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/{team}/threads \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "skip_welcome_message": true,
  "thread": {
    "create_legacy_agent": true,
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org_id": "string",
    "profile_picture": {
      "data": "string",
      "filename": "string",
      "mime_type": "application/json"
    },
    "settings": {
      "agent_enabled": true
    },
    "title": "Example Title"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.threads.create("test-value", { skip_welcome_message: true, thread: { create_legacy_agent: true, description: "An example description.", is_unlisted: true, key: "string", metadata: { key: "value" }, muted: true, org_id: "string", profile_picture: { data: "string", filename: "string", mime_type: "application/json" }, settings: { agent_enabled: true }, title: "Example Title" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.threads.create("test-value", {"skip_welcome_message": True, "thread": {"create_legacy_agent": True, "description": "An example description.", "is_unlisted": True, "key": "string", "metadata": {"key": "value"}, "muted": True, "org_id": "string", "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}, "settings": {"agent_enabled": True}, "title": "Example Title"}})

JSON body

{
  "skip_welcome_message": true,
  "thread": {
    "create_legacy_agent": true,
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org_id": "string",
    "profile_picture": {
      "data": "string",
      "filename": "string",
      "mime_type": "application/json"
    },
    "settings": {
      "agent_enabled": true
    },
    "title": "Example Title"
  }
}

Response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "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"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "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"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "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"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

POST/api/v1/teams/join_by_code

Join a team with an invite code

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.

Bearer tokenPublishable key

Request body

Name	Type	Description
`agent`	string	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.
`invite_code`	string	12-character invite code — alias for `join_code` accepted for backwards compatibility.
`join_code`	string	12-character invite code that identifies the team. Mutually usable with `invite_code`.
`user`	string	User ID (`user_...`) to add to the team. Required for server-to-server requests when `agent` is not supplied.

Responses

200Successful response
400Invalid join code format
401Unauthorized
404Invalid or expired join code
429Too many requests

curl

curl -X POST https://developers.archastro.ai/api/v1/teams/join_by_code \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "agent": "string",
  "invite_code": "string",
  "join_code": "string",
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.teams.joinByCode({ agent: "string", invite_code: "string", join_code: "string", user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.teams.join_by_code({"agent": "string", "invite_code": "string", "join_code": "string", "user": "string"})

JSON body

{
  "agent": "string",
  "invite_code": "string",
  "join_code": "string",
  "user": "string"
}

Response

{
  "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"
}

/api/v1/threads

Threads

15 operations

GET/api/v1/threads/{thread}

Retrieve a thread

Returns the full thread record for the given thread ID. The authenticated user must own the thread or be a member of the workspace it belongs to. Use this endpoint to fetch the current state of a single thread, including its title, description, and metadata. To list many threads, use the list endpoint with cursor-based pagination.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). The authenticated user must have access to this thread.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.get("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.get("string")

Response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "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"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "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"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "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"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

PUT/api/v1/threads/{thread}

Update a thread

Updates one or more mutable properties of the specified thread and returns the full thread object with the applied changes. Only the fields you provide are modified; omitted fields retain their current values. If `profile_picture` is supplied, the image is uploaded before the other fields are saved. Supplying invalid base64 picture data returns 422 and no other fields are updated. The authenticated user must own the thread or be a team owner of the workspace the thread belongs to.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). The authenticated user must have permission to update this thread.

Request body

Name	Type	Description
`description`	string	Optional longer text describing the thread's purpose. Replaces the existing description when provided.
`metadata`	object	Arbitrary key-value metadata to store on the thread. Merged with or replaces existing metadata.
`muted`	boolean	When `true`, suppresses notifications for new messages in this thread for the authenticated user.
`profile_picture`	object	New profile picture for the thread. Provide all three inner fields to replace the existing image.
`title`	string	Human-readable display name for the thread. Replaces the existing title when provided.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found
422Validation failed

curl

curl -X PUT https://developers.archastro.ai/api/v1/threads/{thread} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "description": "An example description.",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "title": "Example Title"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.replace("string", { description: "An example description.", metadata: { key: "value" }, muted: true, profile_picture: { data: "string", filename: "string", mime_type: "application/json" }, title: "Example Title" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.replace("string", {"description": "An example description.", "metadata": {"key": "value"}, "muted": True, "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}, "title": "Example Title"})

JSON body

{
  "description": "An example description.",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  },
  "title": "Example Title"
}

Response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "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"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "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"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "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"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

DELETE/api/v1/threads/{thread}

Delete a thread

Permanently deletes a thread and all of its messages and artifacts. This action cannot be undone. The authenticated user must own the thread or be an owner of the team the thread belongs to. Attempting to delete a thread owned by another user or team returns 403.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). The authenticated user must own this thread.

Responses

204No content
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X DELETE https://developers.archastro.ai/api/v1/threads/{thread} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.threads.delete("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.threads.delete("string")

GET/api/v1/threads/{thread}/agents

List agents in a thread

Returns the agents participating in the specified thread. Only personal user threads (threads owned by a single user, not a team) expose agents through this endpoint; requests for team threads return 404. The authenticated user must have visibility into the thread. Each agent entry includes display information such as name and profile picture. Thread-level overrides (e.g. a custom name or profile picture set for this thread) take precedence over the agent's default values. When the caller is the thread owner, each entry also includes an `agent_config` object describing the agent's message policy and context configuration.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). Must be a personal user thread visible to the authenticated user.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/agents \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.agents("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.agents("string")

Response

{
  "data": [
    {}
  ]
}

GET/api/v1/threads/{thread}/artifacts

List artifacts for a thread

Returns all artifacts produced during a thread's AI conversation. Artifacts are structured outputs such as code files, documents, or generated assets created by the AI agent in response to messages in the thread. The authenticated user must have access to the specified thread. Results are returned in a single page; there is no cursor-based pagination for this endpoint.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). Must be accessible to the authenticated user.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/artifacts \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.artifacts("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.artifacts("string")

Response

{
  "data": [
    {
      "agent": "agt_0aBcDeFgHiJkLmNoPqRsTu",
      "content_type": "application/json",
      "created_at": "2024-01-01T00:00:00Z",
      "current_version": "afv_0aBcDeFgHiJkLmNoPqRsTu",
      "description": "An example description.",
      "file": "string",
      "file_name": "Example Name",
      "file_url": "https://example.com",
      "id": "art_0aBcDeFgHiJkLmNoPqRsTu",
      "image_source": {
        "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
        "height": 600,
        "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
        "mime_type": "application/json",
        "refresh_url": "https://example.com",
        "url": "https://example.com",
        "width": 800
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox": "string",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
      "version": 1
    }
  ]
}

POST/api/v1/threads/{thread}/mark_read

Mark a thread as read

Records that a user has read up to a specific message in the thread. Unread indicators and badge counts are cleared up to the specified message. You must supply exactly one of `last_read_message` or `use_latest_message`. Omitting both returns 400. If `use_latest_message` is `true` and the thread has no messages, the request succeeds silently with no state change. For server-to-server (S2S) requests where no user identity is present in the token, the `user` param is required to identify whose read state to update.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). The thread to mark as read.

Request body

Name	Type	Description
`last_read_message`	string	Message ID (`msg_...`) to record as the last read message. Mutually exclusive with `use_latest_message`.
`use_latest_message`	boolean	When `true`, marks the thread as read up to the latest message. Mutually exclusive with `last_read_message`.
`user`	string	User ID (`usr_...`) whose read state to update. Required for S2S requests; ignored when an authenticated user is present in the token.

Responses

204No content
401Unauthorized
404Thread not found
422Validation error

curl

curl -X POST https://developers.archastro.ai/api/v1/threads/{thread}/mark_read \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "last_read_message": "string",
  "use_latest_message": true,
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.threads.markRead("string", { last_read_message: "string", use_latest_message: true, user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.threads.mark_read("string", {"last_read_message": "string", "use_latest_message": True, "user": "string"})

JSON body

{
  "last_read_message": "string",
  "use_latest_message": true,
  "user": "string"
}

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

List members of a thread

Returns all current members of the specified thread, including both user and agent members. The authenticated user must have visibility into the thread; requests from users without access return 403. Results are returned as a flat array in the `data` field. The list is not paginated — all members are returned in a single response.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`) whose members should be returned.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/members \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.members.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.members.list("test-value")

Response

{
  "data": [
    {
      "membership_type": "member",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "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"
      }
    }
  ]
}

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

Add a member to a thread

Adds a user or agent as a member of the specified thread. The authenticated user must have access to the thread. On success the new membership record is returned with HTTP 201. Supply either `user` or `agent` depending on the value of `type`. Attempting to add a principal that is already a member of the thread returns a 422 error.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`) identifying the thread to add the member to.

Request body

Name	Type	Description
`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`required	string	Kind of principal being added. Must be `"user"` or `"agent"`.
`user`	string	User ID of the principal to add. Required when `type` is `"user"`.

Responses

200Successful response
401Unauthorized
404Thread not found
422Failed to add member

curl

curl -X POST https://developers.archastro.ai/api/v1/threads/{thread}/members \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "agent": "string",
  "membership_type": "string",
  "type": "string",
  "user": "string"
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.members.create("test-value", { agent: "string", membership_type: "string", type: "string", user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.members.create("test-value", {"agent": "string", "membership_type": "string", "type": "string", "user": "string"})

JSON body

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

Response

{
  "membership_type": "member",
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "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"
  }
}

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

Remove a member from a thread

Removes a user or agent membership from the specified thread. The authenticated user must have access to the thread. A successful removal returns HTTP 204 with no response body. Supply either `user` or `agent` depending on the value of `type`. Returns 404 if the thread or the membership record does not exist.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`) identifying the thread to remove the member from.

Responses

204No content
401Unauthorized
404Thread or member not found
422Failed to remove member

curl

curl -X DELETE https://developers.archastro.ai/api/v1/threads/{thread}/members \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

await client.v1.threads.members.remove("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    await client.v1.threads.members.remove("test-value")

GET/api/v1/threads/{thread}/messages

List messages in a thread

Returns a cursor-paginated list of messages belonging to the specified thread, ordered from oldest to newest. Supply `before_cursor` or `after_cursor` (not both) to page through the result set; omit both to receive the most recent page. The authenticated user must have access to the thread's owner (workspace or user). A 403 is returned if the thread exists but is not accessible to the caller; a 404 is returned if the thread does not exist or is not visible to the authenticated user. Pass `include_reply_counts: true` to annotate each message with the number of threaded replies it has received. This adds a small amount of latency and should be omitted when reply counts are not needed.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`limit`query	integer	Maximum number of messages to return per page. Defaults to 20.
`after_cursor`query	string	Opaque cursor returned in a previous response's `after_cursor` field. When provided, returns the page of messages immediately after that position. Cannot be combined with `before_cursor`.
`before_cursor`query	string	Opaque cursor returned in a previous response's `before_cursor` field. When provided, returns the page of messages immediately before that position. Cannot be combined with `after_cursor`.
`thread`pathrequired	string	Thread ID (`thr_...`). The authenticated user must have access to this thread.
`include_reply_counts`query	boolean	When `true`, each message in the response is annotated with its threaded reply count. Defaults to `false`. Adds latency; omit when reply counts are not needed.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/messages \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.messages("string", { limit: 1, afterCursor: "string", beforeCursor: "string", includeReplyCounts: true });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.messages("string", limit=1, after_cursor="string", before_cursor="string", include_reply_counts=True)

Response

{
  "data": {
    "after_cursor": "string",
    "before_cursor": "string",
    "messages": [
      {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      }
    ]
  }
}

PUT/api/v1/threads/{thread}/picture

Update a thread's profile picture

Uploads a new profile picture for the specified thread and returns the updated thread object. The image must be supplied as a base64-encoded string with its MIME type. The authenticated user must own the thread or be a team owner of the workspace the thread belongs to. Supplying invalid base64 data returns 422.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). The authenticated user must have permission to update this thread.

Request body

Name	Type	Description
`picture`required	object	Profile picture payload. Must include the base64-encoded image data and its MIME type.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found
422Invalid base64 data

curl

curl -X PUT https://developers.archastro.ai/api/v1/threads/{thread}/picture \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "picture": {
    "data": "string",
    "filename": "avatar.png",
    "mime_type": "application/json"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.picture("string", { picture: { data: "string", filename: "avatar.png", mime_type: "application/json" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.picture("string", {"picture": {"data": "string", "filename": "avatar.png", "mime_type": "application/json"}})

JSON body

{
  "picture": {
    "data": "string",
    "filename": "avatar.png",
    "mime_type": "application/json"
  }
}

Response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "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"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "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"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "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"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

GET/api/v1/threads/{thread}/read_status

Retrieve a thread's read status

Returns the read status of a thread for the specified user, including the ID of the last message they have read and the number of unread messages remaining. For user-authenticated requests, the status is always returned for the authenticated user and the `user` parameter is ignored. For server-to-server (S2S) requests, the `user` parameter is required and must be a valid user ID. Returns 404 if the thread does not exist or the caller does not have access to it.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). Must be accessible to the authenticated user or, for S2S requests, to the specified user.
`user`query	string	User ID (`usr_...`) whose read status to retrieve. Required for S2S requests; ignored for user-authenticated requests, which always return the status for the authenticated user.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/read_status \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.readStatus("string", { user: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.read_status("string", user="string")

Response

{
  "last_read_message": "string",
  "thread": "string",
  "unread_count": 1
}

GET/api/v1/threads/{thread}/search

Search context items within a thread

Performs a full-text search over context items (messages, files, and other indexed sources) attached to the specified thread. Returns tagged objects whose content matches the query string. Use the `type` param to restrict results to a particular context source. All accessible context source types are searched when `type` is omitted. The authenticated user must have access to the thread.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`type`query	string	Context source type to restrict the search to, e.g. `"thread/messages"`. Omit to search across all context sources for the thread.
`q`queryrequired	string	Full-text search query. Results are ranked by relevance to this string.
`thread`pathrequired	string	Thread ID (`thr_...`). Must be accessible to the authenticated user.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/search \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.search("string", { type: "string", q: "string" });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.search("string", type="string", q="string")

Response

{
  "data": [
    {}
  ]
}

GET/api/v1/threads/{thread}/settings

Retrieve thread settings

Returns the current settings for the specified thread. Settings control per-thread behavior such as whether the AI agent is enabled. The authenticated user must own the thread or be a member of its workspace. If settings have never been explicitly configured, defaults are returned (for example, `agent_enabled` defaults to `true`).

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). Must belong to the authenticated user's workspace.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found

curl

curl -X GET https://developers.archastro.ai/api/v1/threads/{thread}/settings \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.settings.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.settings.list("test-value")

Response

{
  "agent_enabled": true
}

PUT/api/v1/threads/{thread}/settings

Update thread settings

Updates the settings for the specified thread. Only fields included in the `settings` map are modified; omitted fields retain their current values. The authenticated user must own the thread or be a member of its workspace. Returns the full settings object reflecting the state after the update. Validation errors are returned as `422 Unprocessable Entity`.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`thread`pathrequired	string	Thread ID (`thr_...`). Must belong to the authenticated user's workspace.

Request body

Name	Type	Description
`settings`required	object	Map of settings fields to update. Include only the keys you want to change.

Responses

200Successful response
401Unauthorized
403Forbidden
404Thread not found
422Validation error

curl

curl -X PUT https://developers.archastro.ai/api/v1/threads/{thread}/settings \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "settings": {}
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.threads.settings.replace("test-value", { settings: {} });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.threads.settings.replace("test-value", {"settings": {}})

JSON body

{
  "settings": {}
}

Response

{
  "agent_enabled": true
}

/api/v1/users

Users

9 operations

GET/api/v1/users/{user}

Retrieve a user by ID

Returns the user identified by `user`. The authenticated user must share at least one team with the target user; requests for users outside any shared team are rejected with 403. A user may always retrieve their own profile with this endpoint. Use the `GET /users/me` endpoint as a convenience alias for retrieving the authenticated user without specifying an ID.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`user`pathrequired	string	User ID (`usr_...`) of the user to retrieve.

Responses

200Successful response
401Unauthorized
403Forbidden

curl

curl -X GET https://developers.archastro.ai/api/v1/users/{user} \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.get("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.get("string")

Response

{
  "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"
}

GET/api/v1/users/{user}/artifacts

List a user's artifacts

Returns all artifacts owned by the specified user. Artifacts represent AI-generated or user-uploaded files associated with agent sessions, threads, or sandboxes — such as images, documents, and code outputs. The authenticated user must be requesting their own artifacts or must have administrative access. Attempting to list artifacts for a user the caller is not authorized to access returns 403. Results are returned in a single page without cursor pagination. Each artifact in the response reflects the state of its current version, including a short-lived signed `file_url` for direct download.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`user`pathrequired	string	User ID (`usr_...`). The authenticated user must be this user or have access to their artifacts.

Responses

200Successful response
401Unauthorized
403Forbidden

curl

curl -X GET https://developers.archastro.ai/api/v1/users/{user}/artifacts \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.artifacts.list("test-value");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.artifacts.list("test-value")

Response

{
  "data": [
    {
      "agent": "agt_0aBcDeFgHiJkLmNoPqRsTu",
      "content_type": "application/json",
      "created_at": "2024-01-01T00:00:00Z",
      "current_version": "afv_0aBcDeFgHiJkLmNoPqRsTu",
      "description": "An example description.",
      "file": "string",
      "file_name": "Example Name",
      "file_url": "https://example.com",
      "id": "art_0aBcDeFgHiJkLmNoPqRsTu",
      "image_source": {
        "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
        "height": 600,
        "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
        "mime_type": "application/json",
        "refresh_url": "https://example.com",
        "url": "https://example.com",
        "width": 800
      },
      "name": "Example Name",
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox": "string",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
      "version": 1
    }
  ]
}

POST/api/v1/users/{user}/artifacts

Create an artifact

Bearer tokenPublishable key

Request body

Name	Type	Description
`artifact`required	object	Object containing the attributes for the new artifact.

Responses

200Successful response
401Unauthorized
403Forbidden
422Validation error

curl

curl -X POST https://developers.archastro.ai/api/v1/users/{user}/artifacts \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "artifact": {}
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.artifacts.create("test-value", { artifact: {} });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.artifacts.create("test-value", {"artifact": {}})

JSON body

{
  "artifact": {}
}

Response

{
  "agent": "agt_0aBcDeFgHiJkLmNoPqRsTu",
  "content_type": "application/json",
  "created_at": "2024-01-01T00:00:00Z",
  "current_version": "afv_0aBcDeFgHiJkLmNoPqRsTu",
  "description": "An example description.",
  "file": "string",
  "file_name": "Example Name",
  "file_url": "https://example.com",
  "id": "art_0aBcDeFgHiJkLmNoPqRsTu",
  "image_source": {
    "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
    "height": 600,
    "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
    "mime_type": "application/json",
    "refresh_url": "https://example.com",
    "url": "https://example.com",
    "width": 800
  },
  "name": "Example Name",
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "sandbox": "string",
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu",
  "version": 1
}

POST/api/v1/users/{user}/invites

Create a user invite

Creates a new invite for the authenticated user. The invite can optionally be scoped to a specific thread, a persona, or carry arbitrary metadata. The caller receives the new invite object at HTTP 201. The invite key is always generated server-side (192-bit URL-safe random string) and cannot be supplied by the caller. The path `:user` must match the authenticated user. If a `thread_id` is provided, the authenticated user must have permission to invite others to that thread; team threads are not supported and return an error. Supplying a `thread_id` that does not exist or that belongs to a different user returns an error. If a key collision occurs during creation the call returns a 409 conflict — simply retry to generate a new key.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`user`pathrequired	string	User ID (`usr_...`). Must match the authenticated user.

Request body

Name	Type	Description
`invite`required	object	Parameters for the new invite. See the UserInviteCreateParams schema for field details.

Responses

201Successful response
401Unauthorized
403Forbidden
404Thread not found
409Resource already exists
422Validation failed; Invites cannot be created for team threads; Invalid thread id; User context is required

curl

curl -X POST https://developers.archastro.ai/api/v1/users/{user}/invites \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "invite": {
    "metadata": {
      "key": "value"
    },
    "persona_id": "string",
    "thread_id": "string"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.invites("string", { invite: { metadata: { key: "value" }, persona_id: "string", thread_id: "string" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.invites("string", {"invite": {"metadata": {"key": "value"}, "persona_id": "string", "thread_id": "string"}})

JSON body

{
  "invite": {
    "metadata": {
      "key": "value"
    },
    "persona_id": "string",
    "thread_id": "string"
  }
}

Response

{
  "created_at": "2024-01-01T00:00:00Z",
  "id": "uin_0aBcDeFgHiJkLmNoPqRsTu",
  "key": "string",
  "metadata": {
    "key": "value"
  },
  "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
  "user": {
    "id": "usr_0aBcDeFgHiJkLmNoPqRsTu",
    "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
    }
  }
}

GET/api/v1/users/{user}/orgs

List organizations for a user

Returns the organizations the specified user belongs to. A user can belong to at most one organization, so the `data` array contains either zero or one items. The authenticated viewer must have permission to inspect the target user. Returns an empty `data` array when the user has no organization membership.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`user`pathrequired	string	User ID (`usr_...`) whose organization membership you want to retrieve.

Responses

200Successful response
401Unauthorized

curl

curl -X GET https://developers.archastro.ai/api/v1/users/{user}/orgs \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.orgs("string");

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.orgs("string")

Response

{
  "data": [
    {
      "created_at": "2024-01-01T00:00:00Z",
      "description": "An example description.",
      "domain": "acme.com",
      "id": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "industry": "fintech",
      "name": "Example Name",
      "onboarding_track": "vendor",
      "sandbox": "dsb_0aBcDeFgHiJkLmNoPqRsTu",
      "slug": "example-slug",
      "status": "active",
      "updated_at": "2024-01-01T00:00:00Z",
      "website": "https://example.com"
    }
  ]
}

PUT/api/v1/users/{user}/profile

Update the current user's profile

Updates one or more profile fields for the authenticated user. All fields are optional; omit any you do not want to change. When `profile_picture` is supplied, the image is uploaded and replaces the existing picture. The previous picture is deleted after the new one is stored. Image upload failures return 422 without modifying other profile fields.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`user`pathrequired	string	User ID (`usr_...`) or `"me"` for the authenticated user.

Request body

Name	Type	Description
`alias`	string	Short display alias shown in place of the full name in compact UI contexts.
`full_name`	string	Updated display name for the user.
`metadata`	object	Arbitrary key-value metadata to associate with the user. Existing keys are merged; pass `null` for a key to remove it.
`profile_picture`	object	New profile picture to upload as a base64-encoded image. Replaces any existing picture.

Responses

200Successful response
401Unauthorized
422Validation error

curl

curl -X PUT https://developers.archastro.ai/api/v1/users/{user}/profile \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "alias": "string",
  "full_name": "Example Name",
  "metadata": {
    "key": "value"
  },
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.profile("string", { alias: "string", full_name: "Example Name", metadata: { key: "value" }, profile_picture: { data: "string", filename: "string", mime_type: "application/json" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.profile("string", {"alias": "string", "full_name": "Example Name", "metadata": {"key": "value"}, "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}})

JSON body

{
  "alias": "string",
  "full_name": "Example Name",
  "metadata": {
    "key": "value"
  },
  "profile_picture": {
    "data": "string",
    "filename": "string",
    "mime_type": "application/json"
  }
}

Response

{
  "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"
}

GET/api/v1/users/{user}/threads

List threads for a user

Returns all threads visible to the specified user. The authenticated caller must have access to the target user's account; a 403 is returned otherwise. Pass one or more `agent` IDs to narrow results to threads where at least one of the listed agents is also a member — useful for displaying every thread a user shares with a particular agent. Pass one or more `filter` objects to narrow results by thread metadata key/value pairs. Both narrowings may be combined in a single request. Results are returned as a flat array; no cursor-based pagination is applied.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`agent`query	array<string>	Array of agent user IDs (`usr_...`). When provided, only threads where at least one of the listed agents is also a member are returned. Omit or pass an empty array to return all threads regardless of agent membership.
`filter`query	array<object>	Array of metadata filter objects. Each filter matches threads whose `metadata` map contains the specified key/value pair. All filters must match (logical AND). Omit to return threads regardless of metadata.
`user`pathrequired	string	User ID (`usr_...`) whose threads should be listed.

Responses

200Successful response
401Unauthorized
403Forbidden

curl

curl -X GET https://developers.archastro.ai/api/v1/users/{user}/threads \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.threads.list("test-value", { agent: ["string"], filter: [{ key: "string", type: "metadata", value: "string" }] });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.threads.list("test-value", agent=["string"], filter=[{"key", type="metadata", value="string"}])

Response

{
  "data": [
    {
      "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "creator": {
        "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"
      },
      "description": "An example description.",
      "id": "string",
      "is_channel": true,
      "is_default": true,
      "is_transient": true,
      "is_unlisted": true,
      "key": "string",
      "last_activity": "2024-01-01T00:00:00Z",
      "metadata": {
        "key": "value"
      },
      "muted": true,
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "parent_message": {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      },
      "participant": [
        "string"
      ],
      "participants": [
        {
          "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"
        }
      ],
      "participating_actor": [
        "string"
      ],
      "participating_agents": [
        {
          "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"
        }
      ],
      "role": "member",
      "sandbox": "string",
      "settings": {
        "agent_enabled": true
      },
      "slug": "example-slug",
      "sub_threads": [
        {}
      ],
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "title": "Example Title",
      "ttl": 3600,
      "unread_count": 5,
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  ]
}

POST/api/v1/users/{user}/threads

Create a thread for a user

Creates a new thread owned by the specified user. The authenticated caller must have access to the target user's account; a 403 is returned otherwise. An automatic welcome message is sent into the thread upon creation unless `skip_welcome_message` is set to `true`. The thread is immediately visible to the owning user and any members added at creation time.

Bearer tokenPublishable key

Parameters

Name	Type	Description
`user`pathrequired	string	User ID (`usr_...`) of the user who will own the new thread.

Request body

Name	Type	Description
`skip_welcome_message`	boolean	When `true`, suppresses the automatic welcome message that is otherwise sent into the thread on creation. Defaults to `false`.
`thread`required	object	Attributes for the new thread. See ThreadCreateParams for the full set of accepted fields.

Responses

200Successful response
401Unauthorized
403Forbidden
422Validation failed

curl

curl -X POST https://developers.archastro.ai/api/v1/users/{user}/threads \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY" \
  -H "content-type: application/json" \
  -d '{
  "skip_welcome_message": true,
  "thread": {
    "create_legacy_agent": true,
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org_id": "string",
    "profile_picture": {
      "data": "string",
      "filename": "string",
      "mime_type": "application/json"
    },
    "settings": {
      "agent_enabled": true
    },
    "title": "Example Title"
  }
}'

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.threads.create("test-value", { skip_welcome_message: true, thread: { create_legacy_agent: true, description: "An example description.", is_unlisted: true, key: "string", metadata: { key: "value" }, muted: true, org_id: "string", profile_picture: { data: "string", filename: "string", mime_type: "application/json" }, settings: { agent_enabled: true }, title: "Example Title" } });

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.threads.create("test-value", {"skip_welcome_message": True, "thread": {"create_legacy_agent": True, "description": "An example description.", "is_unlisted": True, "key": "string", "metadata": {"key": "value"}, "muted": True, "org_id": "string", "profile_picture": {"data": "string", "filename": "string", "mime_type": "application/json"}, "settings": {"agent_enabled": True}, "title": "Example Title"}})

JSON body

{
  "skip_welcome_message": true,
  "thread": {
    "create_legacy_agent": true,
    "description": "An example description.",
    "is_unlisted": true,
    "key": "string",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org_id": "string",
    "profile_picture": {
      "data": "string",
      "filename": "string",
      "mime_type": "application/json"
    },
    "settings": {
      "agent_enabled": true
    },
    "title": "Example Title"
  }
}

Response

{
  "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "creator": {
    "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"
  },
  "description": "An example description.",
  "id": "string",
  "is_channel": true,
  "is_default": true,
  "is_transient": true,
  "is_unlisted": true,
  "key": "string",
  "last_activity": "2024-01-01T00:00:00Z",
  "metadata": {
    "key": "value"
  },
  "muted": true,
  "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
  "parent_message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "participant": [
    "string"
  ],
  "participants": [
    {
      "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"
    }
  ],
  "participating_actor": [
    "string"
  ],
  "participating_agents": [
    {
      "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"
    }
  ],
  "role": "member",
  "sandbox": "string",
  "settings": {
    "agent_enabled": true
  },
  "slug": "example-slug",
  "sub_threads": [
    {}
  ],
  "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
  "title": "Example Title",
  "ttl": 3600,
  "unread_count": 5,
  "updated_at": "2024-01-01T00:00:00Z",
  "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
}

GET/api/v1/users/me

Retrieve the current user

Returns the user associated with the authenticated session or bearer token. This is the canonical way to resolve "who am I?" after authentication. The response includes the user's profile, notification settings, and profile picture, along with the app, organization, and sandbox the token is scoped to and their display names — enough to establish full session context in a single call. Unauthenticated requests return 401.

Bearer tokenPublishable key

Responses

200Successful response
401Unauthorized

curl

curl -X GET https://developers.archastro.ai/api/v1/users/me \
  -H "Authorization: Bearer $ARCHASTRO_ACCESS_TOKEN" \
  -H "x-archastro-api-key: $ARCHASTRO_PUBLISHABLE_KEY"

TypeScript

import { PlatformClient } from "@archastro/sdk";

const client = new PlatformClient({
  accessToken: process.env.ARCHASTRO_ACCESS_TOKEN,
  defaultHeaders: { "x-archastro-api-key": process.env.ARCHASTRO_API_KEY ?? "" },
});

const result = await client.v1.users.me();

Python

from archastro.platform import AsyncPlatformClient

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    result = await client.v1.users.me()

Response

{
  "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"
}

WebSocket topics

Channels

30 channel entries

Realtime channel documentation is generated from the OpenAPI x-channels extension. Channel replies use the Phoenix-style envelope documented by the channel schemas.

Realtime channel

API Chat Channel

6 joins · 10 messages · 4 pushes

Channel for real-time chat messaging. Supports team-scoped and user-scoped threads with keyed, transient, and direct thread access patterns.

Join topics

JOINapi:chat:team:{team_id}:thread:{thread_id}

Join Team Thread

Join a team-scoped thread by ID

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`limit`	integer	No description provided.
`team_id`required	string	No description provided.
`thread_id`required	string	No description provided.

TypeScript

import { ApiChatChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiChatChannel.topicTeamThread("test-id", "test-id");
const channel = await ApiChatChannel.joinTeamThread(socket, "test-id", "test-id", { after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_chat_channel import ApiChatChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiChatChannel.join_team_thread(
        socket,
        "test-id",
        "test-id",
        after_cursor="test-value",
        before_cursor="test-value",
        include_metadata=True,
        limit=1,
    )

Join params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "limit": 1,
  "team_id": "string",
  "thread_id": "string"
}

{}

JOINapi:chat:team:{team_id}:transient:{key}

Join Team Transient

Join a team-scoped transient (ephemeral) thread

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`key`required	string	No description provided.
`limit`	integer	No description provided.
`team_id`required	string	No description provided.

TypeScript

import { ApiChatChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiChatChannel.topicTeamTransient("test-id", "test-key");
const channel = await ApiChatChannel.joinTeamTransient(socket, "test-id", "test-key", { after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_chat_channel import ApiChatChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiChatChannel.join_team_transient(
        socket,
        "test-id",
        "test-key",
        after_cursor="test-value",
        before_cursor="test-value",
        include_metadata=True,
        limit=1,
    )

Join params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "key": "string",
  "limit": 1,
  "team_id": "string"
}

{}

JOINapi:chat:user:thread:{thread_id}

Join User Thread

Join a user-scoped thread by ID

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`limit`	integer	No description provided.
`thread_id`required	string	No description provided.

TypeScript

import { ApiChatChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiChatChannel.topicUserThread("test-id");
const channel = await ApiChatChannel.joinUserThread(socket, "test-id", { after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_chat_channel import ApiChatChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiChatChannel.join_user_thread(
        socket,
        "test-id",
        after_cursor="test-value",
        before_cursor="test-value",
        include_metadata=True,
        limit=1,
    )

Join params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "limit": 1,
  "thread_id": "string"
}

{}

JOINapi:chat:user:transient:{key}

Join User Transient

Join a user-scoped transient (ephemeral) thread

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`key`required	string	No description provided.
`limit`	integer	No description provided.

TypeScript

import { ApiChatChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiChatChannel.topicUserTransient("test-key");
const channel = await ApiChatChannel.joinUserTransient(socket, "test-key", { after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_chat_channel import ApiChatChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiChatChannel.join_user_transient(
        socket,
        "test-key",
        after_cursor="test-value",
        before_cursor="test-value",
        include_metadata=True,
        limit=1,
    )

Join params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "key": "string",
  "limit": 1
}

{}

JOINapi:chat:team:{team_id}:key:{key}

Join Team Keyed

Join or create a team-scoped keyed thread

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`key`required	string	No description provided.
`limit`	integer	No description provided.
`team_id`required	string	No description provided.

TypeScript

import { ApiChatChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiChatChannel.topicTeamKeyed("test-id", "test-key");
const channel = await ApiChatChannel.joinTeamKeyed(socket, "test-id", "test-key", { after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_chat_channel import ApiChatChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiChatChannel.join_team_keyed(
        socket,
        "test-id",
        "test-key",
        after_cursor="test-value",
        before_cursor="test-value",
        include_metadata=True,
        limit=1,
    )

Join params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "key": "string",
  "limit": 1,
  "team_id": "string"
}

{}

JOINapi:chat:user:key:{key}

Join User Keyed

Join or create a user-scoped keyed thread

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`key`required	string	No description provided.
`limit`	integer	No description provided.

TypeScript

import { ApiChatChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiChatChannel.topicUserKeyed("test-key");
const channel = await ApiChatChannel.joinUserKeyed(socket, "test-key", { after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_chat_channel import ApiChatChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiChatChannel.join_user_keyed(
        socket,
        "test-key",
        after_cursor="test-value",
        before_cursor="test-value",
        include_metadata=True,
        limit=1,
    )

Join params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "key": "string",
  "limit": 1
}

{}

Messages

EVENTapi:chat:add_reaction

Add Reaction

Add an emoji reaction to a message

Payload fields

Name	Type	Description
`emoji`required	string	No description provided.
`message_id`required	string	No description provided.

TypeScript

const reply = await channel.apiChatAddReaction({ emoji: "test-value", message_id: "test-id" });

Python

reply = await channel.api_chat_add_reaction({
    "emoji": "test-value",
    "message_id": "test-id",
})

Message params

{
  "emoji": "string",
  "message_id": "string"
}

{}

EVENTapi:chat:delete_message

Delete Message

Delete a message

Payload fields

Name	Type	Description
`message_id`required	string	No description provided.

TypeScript

const reply = await channel.apiChatDeleteMessage({ message_id: "test-id" });

Python

reply = await channel.api_chat_delete_message({
    "message_id": "test-id",
})

Message params

{
  "message_id": "string"
}

{}

EVENTapi:chat:edit_message

Edit Message

Edit an existing message's content

Payload fields

Name	Type	Description
`content`required	string	No description provided.
`message_id`required	string	No description provided.

TypeScript

const reply = await channel.apiChatEditMessage({ content: "test content", message_id: "test-id" });

Python

reply = await channel.api_chat_edit_message({
    "content": "test content",
    "message_id": "test-id",
})

Message params

{
  "content": "string",
  "message_id": "string"
}

{}

EVENTapi:chat:fork_thread

Fork Thread

Fork a sub-thread from an existing message

Payload fields

Name	Type	Description
`message_id`required	string	No description provided.
`title`	string	No description provided.

TypeScript

const reply = await channel.apiChatForkThread({ message_id: "test-id", title: "test-value" });

Python

reply = await channel.api_chat_fork_thread({
    "message_id": "test-id",
    "title": "test-value",
})

Message params

{
  "message_id": "string",
  "title": "Example Title"
}

{
  "chat_model": {
    "after_cursor": "string",
    "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"
    },
    "before_cursor": "string",
    "is_transient": true,
    "members": [
      {
        "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"
        }
      }
    ],
    "messages": [
      {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      }
    ],
    "messages_loaded_on_last_update": 1,
    "team": {
      "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"
    },
    "thread": {
      "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "creator": {
        "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"
      },
      "description": "An example description.",
      "id": "string",
      "is_channel": true,
      "is_default": true,
      "is_transient": true,
      "is_unlisted": true,
      "key": "string",
      "last_activity": "2024-01-01T00:00:00Z",
      "metadata": {
        "key": "value"
      },
      "muted": true,
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "parent_message": {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      },
      "participant": [
        "string"
      ],
      "participants": [
        {
          "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"
        }
      ],
      "participating_actor": [
        "string"
      ],
      "participating_agents": [
        {
          "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"
        }
      ],
      "role": "member",
      "sandbox": "string",
      "settings": {
        "agent_enabled": true
      },
      "slug": "example-slug",
      "sub_threads": [
        {}
      ],
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "title": "Example Title",
      "ttl": 3600,
      "unread_count": 5,
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  },
  "team": {
    "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"
  },
  "thread": {
    "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "created_at": "2024-01-01T00:00:00Z",
    "creator": {
      "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"
    },
    "description": "An example description.",
    "id": "string",
    "is_channel": true,
    "is_default": true,
    "is_transient": true,
    "is_unlisted": true,
    "key": "string",
    "last_activity": "2024-01-01T00:00:00Z",
    "metadata": {
      "key": "value"
    },
    "muted": true,
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "parent_message": {
      "actors": [
        {
          "alias": "alice",
          "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
          "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
          }
        }
      ],
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "attachments": [
        {
          "content_type": "application/json",
          "description": "An example description.",
          "filename": "string",
          "height": 1,
          "id": "string",
          "image_height": 1,
          "image_source": {
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "height": 600,
            "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
            "mime_type": "application/json",
            "refresh_url": "https://example.com",
            "url": "https://example.com",
            "width": 800
          },
          "image_url": "https://example.com",
          "image_width": 1,
          "media_type": "application/json",
          "name": "Example Name",
          "object": {},
          "title": "Example Title",
          "type": "file",
          "url": "https://example.com",
          "variants": [
            {
              "content_type": "application/json",
              "created_at": "2024-01-01T00:00:00Z",
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "filename": "string",
              "height": 600,
              "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
              "image_source": {
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "height": 600,
                "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                "mime_type": "application/json",
                "refresh_url": "https://example.com",
                "url": "https://example.com",
                "width": 800
              },
              "updated_at": "2024-01-01T00:00:00Z",
              "url": "https://example.com",
              "variant_key": "original",
              "width": 800
            }
          ],
          "version": 1,
          "width": 1
        }
      ],
      "branched_thread": "string",
      "content": "Hello, how can I help you today?",
      "created_at": "2024-01-01T00:00:00Z",
      "has_replies": true,
      "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
      "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
      "legacy_agent": "string",
      "metadata": {
        "key": "value"
      },
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "reactions": [
        {
          "payload": {
            "key": "value"
          },
          "type": "emoji_reaction",
          "user": "string"
        }
      ],
      "rendering_mode": "reply",
      "replies": [
        {}
      ],
      "replies_after_cursor": "string",
      "replies_before_cursor": "string",
      "reply_count": 1,
      "reply_to": {},
      "sandbox": "string",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "string",
      "user": "string"
    },
    "participant": [
      "string"
    ],
    "participants": [
      {
        "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"
      }
    ],
    "participating_actor": [
      "string"
    ],
    "participating_agents": [
      {
        "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"
      }
    ],
    "role": "member",
    "sandbox": "string",
    "settings": {
      "agent_enabled": true
    },
    "slug": "example-slug",
    "sub_threads": [
      {}
    ],
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "title": "Example Title",
    "ttl": 3600,
    "unread_count": 5,
    "updated_at": "2024-01-01T00:00:00Z",
    "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
  }
}

EVENTapi:chat:list_messages

List Messages

List all messages in the current thread

TypeScript

const reply = await channel.apiChatListMessages({});

Python

reply = await channel.api_chat_list_messages({
})

Message params

{}

{
  "messages": [
    {
      "actors": [
        {
          "alias": "alice",
          "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
          "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
          }
        }
      ],
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "attachments": [
        {
          "content_type": "application/json",
          "description": "An example description.",
          "filename": "string",
          "height": 1,
          "id": "string",
          "image_height": 1,
          "image_source": {
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "height": 600,
            "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
            "mime_type": "application/json",
            "refresh_url": "https://example.com",
            "url": "https://example.com",
            "width": 800
          },
          "image_url": "https://example.com",
          "image_width": 1,
          "media_type": "application/json",
          "name": "Example Name",
          "object": {},
          "title": "Example Title",
          "type": "file",
          "url": "https://example.com",
          "variants": [
            {
              "content_type": "application/json",
              "created_at": "2024-01-01T00:00:00Z",
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "filename": "string",
              "height": 600,
              "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
              "image_source": {
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "height": 600,
                "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                "mime_type": "application/json",
                "refresh_url": "https://example.com",
                "url": "https://example.com",
                "width": 800
              },
              "updated_at": "2024-01-01T00:00:00Z",
              "url": "https://example.com",
              "variant_key": "original",
              "width": 800
            }
          ],
          "version": 1,
          "width": 1
        }
      ],
      "branched_thread": "string",
      "content": "Hello, how can I help you today?",
      "created_at": "2024-01-01T00:00:00Z",
      "has_replies": true,
      "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
      "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
      "legacy_agent": "string",
      "metadata": {
        "key": "value"
      },
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "reactions": [
        {
          "payload": {
            "key": "value"
          },
          "type": "emoji_reaction",
          "user": "string"
        }
      ],
      "rendering_mode": "reply",
      "replies": [
        {}
      ],
      "replies_after_cursor": "string",
      "replies_before_cursor": "string",
      "reply_count": 1,
      "reply_to": {},
      "sandbox": "string",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "string",
      "user": "string"
    }
  ]
}

EVENTapi:chat:load_more_messages

Load More Messages

Load additional messages with cursor-based pagination

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`include_metadata`	boolean	No description provided.
`limit`	integer	No description provided.

TypeScript

const reply = await channel.apiChatLoadMoreMessages({ after_cursor: "test-value", before_cursor: "test-value", include_metadata: true, limit: 1 });

Python

reply = await channel.api_chat_load_more_messages({
    "after_cursor": "test-value",
    "before_cursor": "test-value",
    "include_metadata": True,
    "limit": 1,
})

Message params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "include_metadata": true,
  "limit": 1
}

{
  "data": {
    "after_cursor": "string",
    "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"
    },
    "before_cursor": "string",
    "is_transient": true,
    "members": [
      {
        "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"
        }
      }
    ],
    "messages": [
      {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      }
    ],
    "messages_loaded_on_last_update": 1,
    "team": {
      "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"
    },
    "thread": {
      "agent_user": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "created_at": "2024-01-01T00:00:00Z",
      "creator": {
        "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"
      },
      "description": "An example description.",
      "id": "string",
      "is_channel": true,
      "is_default": true,
      "is_transient": true,
      "is_unlisted": true,
      "key": "string",
      "last_activity": "2024-01-01T00:00:00Z",
      "metadata": {
        "key": "value"
      },
      "muted": true,
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "parent_message": {
        "actors": [
          {
            "alias": "alice",
            "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
            "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
            }
          }
        ],
        "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
        "attachments": [
          {
            "content_type": "application/json",
            "description": "An example description.",
            "filename": "string",
            "height": 1,
            "id": "string",
            "image_height": 1,
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "image_url": "https://example.com",
            "image_width": 1,
            "media_type": "application/json",
            "name": "Example Name",
            "object": {},
            "title": "Example Title",
            "type": "file",
            "url": "https://example.com",
            "variants": [
              {
                "content_type": "application/json",
                "created_at": "2024-01-01T00:00:00Z",
                "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                "filename": "string",
                "height": 600,
                "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
                "image_source": {
                  "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
                  "height": 600,
                  "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
                  "mime_type": "application/json",
                  "refresh_url": "https://example.com",
                  "url": "https://example.com",
                  "width": 800
                },
                "updated_at": "2024-01-01T00:00:00Z",
                "url": "https://example.com",
                "variant_key": "original",
                "width": 800
              }
            ],
            "version": 1,
            "width": 1
          }
        ],
        "branched_thread": "string",
        "content": "Hello, how can I help you today?",
        "created_at": "2024-01-01T00:00:00Z",
        "has_replies": true,
        "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
        "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
        "legacy_agent": "string",
        "metadata": {
          "key": "value"
        },
        "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
        "reactions": [
          {
            "payload": {
              "key": "value"
            },
            "type": "emoji_reaction",
            "user": "string"
          }
        ],
        "rendering_mode": "reply",
        "replies": [
          {}
        ],
        "replies_after_cursor": "string",
        "replies_before_cursor": "string",
        "reply_count": 1,
        "reply_to": {},
        "sandbox": "string",
        "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
        "thread": "string",
        "user": "string"
      },
      "participant": [
        "string"
      ],
      "participants": [
        {
          "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"
        }
      ],
      "participating_actor": [
        "string"
      ],
      "participating_agents": [
        {
          "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"
        }
      ],
      "role": "member",
      "sandbox": "string",
      "settings": {
        "agent_enabled": true
      },
      "slug": "example-slug",
      "sub_threads": [
        {}
      ],
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "title": "Example Title",
      "ttl": 3600,
      "unread_count": 5,
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  }
}

EVENTapi:chat:mark_thread_read

Mark Thread Read

Mark a thread as read up to a given message

Payload fields

Name	Type	Description
`message_id`required	string	No description provided.

TypeScript

const reply = await channel.apiChatMarkThreadRead({ message_id: "test-id" });

Python

reply = await channel.api_chat_mark_thread_read({
    "message_id": "test-id",
})

Message params

{
  "message_id": "string"
}

{
  "success": true
}

EVENTapi:chat:post_message

Post Message

Post a new message with optional uploads and reply-to

Payload fields

Name	Type	Description
`content`required	string	No description provided.
`idempotency_key`	string	No description provided.
`reply_to`	string	No description provided.
`uploads`	array<object>	No description provided.

TypeScript

const reply = await channel.apiChatPostMessage({ content: "test content", idempotency_key: "test-key", reply_to: "test-value", uploads: [{}] });

Python

reply = await channel.api_chat_post_message({
    "content": "test content",
    "idempotency_key": "test-key",
    "reply_to": "test-value",
    "uploads": [{}],
})

Message params

{
  "content": "string",
  "idempotency_key": "string",
  "reply_to": "string",
  "uploads": [
    {}
  ]
}

{
  "message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  }
}

EVENTapi:chat:post_simple_message

Post Simple Message

Post a simple text message

Payload fields

Name	Type	Description
`content`	string	No description provided.
`idempotency_key`	string	No description provided.
`reply_to`	string	No description provided.

TypeScript

const reply = await channel.apiChatPostSimpleMessage({ content: "test content", idempotency_key: "test-key", reply_to: "test-value" });

Python

reply = await channel.api_chat_post_simple_message({
    "content": "test content",
    "idempotency_key": "test-key",
    "reply_to": "test-value",
})

Message params

{
  "content": "string",
  "idempotency_key": "string",
  "reply_to": "string"
}

{
  "message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  }
}

EVENTapi:chat:remove_reaction

Remove Reaction

Remove an emoji reaction from a message

Payload fields

Name	Type	Description
`emoji`required	string	No description provided.
`message_id`required	string	No description provided.

TypeScript

const reply = await channel.apiChatRemoveReaction({ emoji: "test-value", message_id: "test-id" });

Python

reply = await channel.api_chat_remove_reaction({
    "emoji": "test-value",
    "message_id": "test-id",
})

Message params

{
  "emoji": "string",
  "message_id": "string"
}

{}

Pushes

PUSHsystem_event

System Event

Broadcast system-wide events

Payload fields

Name	Type	Description
`event`	object	No description provided.

TypeScript

const unsubscribe = channel.onSystemEvent((payload) => {
  console.log("system_event", payload);
});

Python

def handle_system_event(payload):
    print(payload)

unsubscribe = channel.on_system_event(handle_system_event)

Payload

{
  "event": {}
}

PUSHthread_event

Thread Event

Broadcast thread-level events (agent updates, read state, unread counts)

Payload fields

Name	Type	Description
`payload`	object	No description provided.
`thread_id`	string	No description provided.
`type`	string	No description provided.

TypeScript

const unsubscribe = channel.onThreadEvent((payload) => {
  console.log("thread_event", payload);
});

Python

def handle_thread_event(payload):
    print(payload)

unsubscribe = channel.on_thread_event(handle_thread_event)

Payload

{
  "payload": {},
  "thread_id": "string",
  "type": "string"
}

PUSHmessage_updated

Message Updated

Broadcast when a message is updated or removed

Payload fields

Name	Type	Description
`message`	object	A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata.
`thread_id`	string	No description provided.

TypeScript

const unsubscribe = channel.onMessageUpdated((payload) => {
  console.log("message_updated", payload);
});

Python

def handle_message_updated(payload):
    print(payload)

unsubscribe = channel.on_message_updated(handle_message_updated)

Payload

{
  "message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "thread_id": "string"
}

PUSHmessage_added

Message Added

Broadcast when a new message is added to a thread

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`message`	object	A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata.
`thread_id`	string	No description provided.

TypeScript

const unsubscribe = channel.onMessageAdded((payload) => {
  console.log("message_added", payload);
});

Python

def handle_message_added(payload):
    print(payload)

unsubscribe = channel.on_message_added(handle_message_added)

Payload

{
  "after_cursor": "string",
  "before_cursor": "string",
  "message": {
    "actors": [
      {
        "alias": "alice",
        "id": "user-usr_01j3k5m7n9p2r4s6t8v0w1x2",
        "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
        }
      }
    ],
    "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
    "attachments": [
      {
        "content_type": "application/json",
        "description": "An example description.",
        "filename": "string",
        "height": 1,
        "id": "string",
        "image_height": 1,
        "image_source": {
          "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
          "height": 600,
          "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
          "mime_type": "application/json",
          "refresh_url": "https://example.com",
          "url": "https://example.com",
          "width": 800
        },
        "image_url": "https://example.com",
        "image_width": 1,
        "media_type": "application/json",
        "name": "Example Name",
        "object": {},
        "title": "Example Title",
        "type": "file",
        "url": "https://example.com",
        "variants": [
          {
            "content_type": "application/json",
            "created_at": "2024-01-01T00:00:00Z",
            "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
            "filename": "string",
            "height": 600,
            "id": "mvr_0aBcDeFgHiJkLmNoPqRsTu",
            "image_source": {
              "file": "fil_0aBcDeFgHiJkLmNoPqRsTu",
              "height": 600,
              "media": "med_0aBcDeFgHiJkLmNoPqRsTu",
              "mime_type": "application/json",
              "refresh_url": "https://example.com",
              "url": "https://example.com",
              "width": 800
            },
            "updated_at": "2024-01-01T00:00:00Z",
            "url": "https://example.com",
            "variant_key": "original",
            "width": 800
          }
        ],
        "version": 1,
        "width": 1
      }
    ],
    "branched_thread": "string",
    "content": "Hello, how can I help you today?",
    "created_at": "2024-01-01T00:00:00Z",
    "has_replies": true,
    "id": "msg_0aBcDeFgHiJkLmNoPqRsTu",
    "idempotency_key": "01234567-89ab-cdef-0123-456789abcdef",
    "legacy_agent": "string",
    "metadata": {
      "key": "value"
    },
    "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
    "reactions": [
      {
        "payload": {
          "key": "value"
        },
        "type": "emoji_reaction",
        "user": "string"
      }
    ],
    "rendering_mode": "reply",
    "replies": [
      {}
    ],
    "replies_after_cursor": "string",
    "replies_before_cursor": "string",
    "reply_count": 1,
    "reply_to": {},
    "sandbox": "string",
    "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
    "thread": "string",
    "user": "string"
  },
  "thread_id": "string"
}

Realtime channel

API Object Channel

2 joins · 2 messages · 2 pushes

Channel for real-time custom object collaboration. Clients join `api:object:{object_id}` to receive the current object state and subscribe to field-level updates. Mutations are sent as key:value maps.

Join topics

JOINapi:object:{object_id}

Join By Id

Payload fields

Name	Type	Description
`object_id`required	string	No description provided.

TypeScript

import { ApiObjectChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiObjectChannel.topicById("test-id");
const channel = await ApiObjectChannel.joinById(socket, "test-id");

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_object_channel import ApiObjectChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiObjectChannel.join_by_id(
        socket,
        "test-id",
    )

Join params

{
  "object_id": "string"
}

{}

JOINapi:object:{schema_type}:{row_key}

Join By Row Key

Payload fields

Name	Type	Description
`row_key`required	string	No description provided.
`schema_type`required	string	No description provided.

TypeScript

import { ApiObjectChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiObjectChannel.topicByRowKey("test-value", "test-key");
const channel = await ApiObjectChannel.joinByRowKey(socket, "test-value", "test-key");

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_object_channel import ApiObjectChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiObjectChannel.join_by_row_key(
        socket,
        "test-value",
        "test-key",
    )

Join params

{
  "row_key": "string",
  "schema_type": "string"
}

{}

Messages

EVENTsave

Save

EVENTupdate_fields

Update Fields

Payload fields

Name	Type	Description
`fields`required	object	No description provided.

TypeScript

const reply = await channel.updateFields({ fields: {} });

Python

reply = await channel.update_fields({
    "fields": {},
})

Message params

{
  "fields": {}
}

{
  "fields": {
    "key": "value"
  },
  "id": "cobj_0aBcDeFgHiJkLmNoPqRsTu"
}

Pushes

PUSHobject_created

Object Created

Payload fields

Name	Type	Description
`fields`	object	No description provided.
`id`	string	No description provided.

TypeScript

const unsubscribe = channel.onObjectCreated((payload) => {
  console.log("object_created", payload);
});

Python

def handle_object_created(payload):
    print(payload)

unsubscribe = channel.on_object_created(handle_object_created)

Payload

{
  "fields": {},
  "id": "string"
}

PUSHobject_updated

Object Updated

Payload fields

Name	Type	Description
`fields`	object	No description provided.
`id`	string	No description provided.

TypeScript

const unsubscribe = channel.onObjectUpdated((payload) => {
  console.log("object_updated", payload);
});

Python

def handle_object_updated(payload):
    print(payload)

unsubscribe = channel.on_object_updated(handle_object_updated)

Payload

{
  "fields": {},
  "id": "string"
}

Realtime channel

API Activity Feed Channel

2 joins · 1 messages · 1 pushes

Phoenix channel for real-time activity feed updates. Clients join a topic scoped to an agent or org and receive `new_entry` events as feed entries are created. ## Topics * `"api:activity_feed:agent:{agent_user_id}"` — entries for a specific agent * `"api:activity_feed:org:{org_id}"` — entries for an entire org/tenant

Join topics

JOINapi:activity_feed:agent:{agent_id}

Join Agent

Join an agent-scoped activity feed

Payload fields

Name	Type	Description
`agent_id`required	string	No description provided.

TypeScript

import { ApiActivityFeedChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiActivityFeedChannel.topicAgent("test-id");
const channel = await ApiActivityFeedChannel.joinAgent(socket, "test-id");

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_activity_feed_channel import ApiActivityFeedChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiActivityFeedChannel.join_agent(
        socket,
        "test-id",
    )

Join params

{
  "agent_id": "string"
}

{}

JOINapi:activity_feed:org:{org_id}

Join Org

Join an org-scoped activity feed

Payload fields

Name	Type	Description
`org_id`required	string	No description provided.

TypeScript

import { ApiActivityFeedChannel } from "@archastro/sdk";
import { Socket } from "@archastro/sdk/phx_channel";

const socket = new Socket("wss://platform.archastro.ai/socket/api/websocket", {
  params: { token: process.env.ARCHASTRO_ACCESS_TOKEN ?? "" },
});
await socket.connect();

const topic = ApiActivityFeedChannel.topicOrg("test-id");
const channel = await ApiActivityFeedChannel.joinOrg(socket, "test-id");

Python

from archastro.platform import AsyncPlatformClient
from archastro.platform.channels.api_activity_feed_channel import ApiActivityFeedChannel

async with AsyncPlatformClient.with_token(api_key, access_token) as client:
    socket = await client.open_socket()
    channel = await ApiActivityFeedChannel.join_org(
        socket,
        "test-id",
    )

Join params

{
  "org_id": "string"
}

{}

Messages

EVENTlist_entries

List Entries

List activity feed entries with cursor-based pagination

Payload fields

Name	Type	Description
`after_cursor`	string	No description provided.
`before_cursor`	string	No description provided.
`kind`	string	No description provided.
`level`	string	No description provided.
`limit`	integer	No description provided.

TypeScript

const reply = await channel.listEntries({ after_cursor: "test-value", before_cursor: "test-value", kind: "test", level: "test-value", limit: 1 });

Python

reply = await channel.list_entries({
    "after_cursor": "test-value",
    "before_cursor": "test-value",
    "kind": "test",
    "level": "test-value",
    "limit": 1,
})

Message params

{
  "after_cursor": "string",
  "before_cursor": "string",
  "kind": "string",
  "level": "string",
  "limit": 1
}

{
  "after_cursor": "string",
  "before_cursor": "string",
  "entries": [
    {
      "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
      "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
      "attachments": [
        {}
      ],
      "automation_run": "atr_0aBcDeFgHiJkLmNoPqRsTu",
      "content": "The agent completed the task successfully.",
      "correlation_id": "01234567-89ab-cdef-0123-456789abcdef",
      "created_at": "2024-01-01T00:00:00Z",
      "id": "afe_0aBcDeFgHiJkLmNoPqRsTu",
      "kind": "agent_step",
      "level": "info",
      "metadata": {
        "key": "value"
      },
      "org": "org_0aBcDeFgHiJkLmNoPqRsTu",
      "routine_run": "arr_0aBcDeFgHiJkLmNoPqRsTu",
      "sandbox": "string",
      "session_record": "ase_0aBcDeFgHiJkLmNoPqRsTu",
      "team": "tem_0aBcDeFgHiJkLmNoPqRsTu",
      "thread": "thr_0aBcDeFgHiJkLmNoPqRsTu",
      "title": "Example Title",
      "updated_at": "2024-01-01T00:00:00Z",
      "user": "usr_0aBcDeFgHiJkLmNoPqRsTu"
    }
  ],
  "has_more": true
}

Pushes

PUSHnew_entry

New Entry

Payload fields

Name	Type	Description
`entry`	object	No description provided.

TypeScript

const unsubscribe = channel.onNewEntry((payload) => {
  console.log("new_entry", payload);
});

Python

def handle_new_entry(payload):
    print(payload)

unsubscribe = channel.on_new_entry(handle_new_entry)

Payload

{
  "entry": {}
}