ArchAstro

ArchAstro

Developer Docs

API Reference

External API reference for authentication, runtime resources, and developer control-plane operations.

Base URL: https://api.archastro.ai

The ArchAstro API is organized into three externally documented scope families:

  • Public auth for login, OAuth, and token exchange
  • Runtime for user and team resources such as threads, messages, tasks, and connected services
  • Developer control-plane for app configuration, agents, routines, workflows, webhooks, and other developer operations under the reviewed developer surface

For the machine-readable external API surface, use /openapi.json.

API scopes

Public auth scope

  • /api/v2/auth/...
  • /oauth/...

Runtime scopes

  • /api/v2/users/...
  • /api/v2/teams/...
  • /api/v2/agents/...
  • /api/v2/connectors/...
  • selected top-level runtime endpoints such as /api/v2/scrape, /api/v2/search, and /api/v2/feedback

Developer control-plane scope

  • /protected/api/v2/developer/me
  • /protected/api/v2/developer/invites/:token/accept
  • /protected/api/v2/developer/apps
  • reviewed app-scoped families under /protected/api/v2/developer/apps/:app_id/...

Internal-only observability, analytics, and execution-debug helpers are intentionally excluded from the public docs artifact even when they exist internally.

Authentication

API keys

Key Type Prefix Use
Publishable pk_live_ Client initialization
Secret sk_live_ Trusted server operations

Create keys in developers.archastro.ai.

Headers

Use one of:

Authorization: Bearer <token_or_api_key>

x-api-key: <api_key>

For user actions after login, use JWT access tokens in Authorization.

Auth flows

  • POST /api/v2/auth/register
  • POST /api/v2/auth/login
  • POST /api/v2/auth/login/link
  • POST /api/v2/auth/verify/link
  • POST /api/v2/auth/login/code
  • POST /api/v2/auth/code/verify
  • POST /api/v2/auth/refresh
  • POST /api/v2/auth/oauth
  • POST /api/v2/auth/token
  • POST /oauth/device/authorize
  • POST /oauth/token

Use device flow for CLI and other non-browser clients.

Developer control-plane surface

These app-scoped endpoints are available from @archastro/sdk and the developer portal.

Agents

GET    /protected/api/v2/developer/apps/:app_id/agents
POST   /protected/api/v2/developer/apps/:app_id/agents
GET    /protected/api/v2/developer/apps/:app_id/agents/:agent_id
PATCH  /protected/api/v2/developer/apps/:app_id/agents/:agent_id
DELETE /protected/api/v2/developer/apps/:app_id/agents/:agent_id

Teams and organizations

GET    /protected/api/v2/developer/apps/:app_id/teams
POST   /protected/api/v2/developer/apps/:app_id/teams
GET    /protected/api/v2/developer/apps/:app_id/teams/:team_id
PATCH  /protected/api/v2/developer/apps/:app_id/teams/:team_id
GET    /protected/api/v2/developer/apps/:app_id/teams/:team_id/members
POST   /protected/api/v2/developer/apps/:app_id/teams/:team_id/members
DELETE /protected/api/v2/developer/apps/:app_id/teams/:team_id/members/:user_id

GET    /protected/api/v2/developer/apps/:app_id/orgs
POST   /protected/api/v2/developer/apps/:app_id/orgs
GET    /protected/api/v2/developer/apps/:app_id/orgs/:id
PATCH  /protected/api/v2/developer/apps/:app_id/orgs/:id
DELETE /protected/api/v2/developer/apps/:app_id/orgs/:id

Routines, workflows, and automations

GET    /protected/api/v2/developer/apps/:app_id/routines
POST   /protected/api/v2/developer/apps/:app_id/agents/:agent_id/routines
PATCH  /protected/api/v2/developer/apps/:app_id/routines/:routine_id
POST   /protected/api/v2/developer/apps/:app_id/routines/:routine_id/activate
POST   /protected/api/v2/developer/apps/:app_id/routines/:routine_id/pause

POST   /protected/api/v2/developer/apps/:app_id/workflows/run
GET    /protected/api/v2/developer/apps/:app_id/workflows/node-types
GET    /protected/api/v2/developer/apps/:app_id/workflows/scripts/language

Installations and context

GET    /protected/api/v2/developer/apps/:app_id/installations
GET    /protected/api/v2/developer/apps/:app_id/installations/kinds
POST   /protected/api/v2/developer/apps/:app_id/agents/:agent_id/installations
POST   /protected/api/v2/developer/apps/:app_id/installations/:installation_id/activate

GET/POST /protected/api/v2/developer/apps/:app_id/context/sources
GET/POST /protected/api/v2/developer/apps/:app_id/context/integrations
GET/POST /protected/api/v2/developer/apps/:app_id/context/credentials

Other common developer surfaces

Also available under reviewed app-scoped families such as /protected/api/v2/developer/apps/:app_id/...:

  • configs
  • webhooks
  • oauth_providers
  • oauth_clients
  • keys
  • domains
  • files
  • custom_objects
  • sandboxes
  • users
  • members
  • personas

Runtime surface

Users

GET   /api/v2/users/me
GET   /api/v2/users/:user_id
PATCH /api/v2/users/:user_id/profile
PATCH /api/v2/users/:user_id/email
PATCH /api/v2/users/:user_id/timezone

Agents

GET    /api/v2/agents
POST   /api/v2/agents
GET    /api/v2/agents/:agent_id
PATCH  /api/v2/agents/:agent_id
DELETE /api/v2/agents/:agent_id

Threads

GET    /api/v2/users/:user_id/threads
POST   /api/v2/users/:user_id/threads
GET    /api/v2/users/:user_id/threads/:thread_id
PATCH  /api/v2/users/:user_id/threads/:thread_id
DELETE /api/v2/users/:user_id/threads/:thread_id

GET    /api/v2/teams/:team_id/threads
POST   /api/v2/teams/:team_id/threads
GET    /api/v2/teams/:team_id/threads/:thread_id
PATCH  /api/v2/teams/:team_id/threads/:thread_id
DELETE /api/v2/teams/:team_id/threads/:thread_id

Messages

GET  /api/v2/users/:user_id/threads/:thread_id/messages
POST /api/v2/users/:user_id/threads/:thread_id/messages
GET  /api/v2/teams/:team_id/threads/:thread_id/messages
POST /api/v2/teams/:team_id/threads/:thread_id/messages

Teams, memberships, and invitations

GET  /api/v2/teams
POST /api/v2/teams
GET  /api/v2/teams/:team_id
PUT  /api/v2/teams/:team_id
GET  /api/v2/teams/:team_id/members
POST /api/v2/teams/:team_id/invite
POST /api/v2/teams/join

Tasks, objects, artifacts, and integrations

Representative runtime endpoints include:

GET  /api/v2/teams/:team_id/tasks
GET  /api/v2/teams/:team_id/objects
POST /api/v2/scrape
POST /api/v2/search
POST /api/v2/feedback
GET  /api/v2/users/:user_id/integrations
POST /webhooks/:app_id/:provider_or_key

WebSocket channels

Real-time communication uses WebSocket channels.

Connection URL: wss://api.archastro.ai/socket/websocket

Topic Purpose
user:<user_id> User presence, notifications, direct events
team:<team_id> Team-wide events and member activity
thread:<thread_id> Thread messages, typing indicators, and agent responses

Pagination

The API uses both cursor-based and offset-based pagination depending on the resource type.

Examples:

GET /api/v2/users/:user_id/threads/:thread_id/messages?limit=50&before_cursor=msg_abc123

GET /api/v2/teams/:team_id/tasks?limit=25&offset=0

Error format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "not_found",
    "message": "Thread not found",
    "details": {}
  }
}

Common HTTP status codes:

Code Meaning
400 Invalid request
401 Authentication required
403 Forbidden
404 Resource not found
422 Validation failed
500 Internal server error