API Reference

The Scion ecosystem exposes several APIs for coordination, management, and observability. This reference provides an overview of the primary resource types and communication patterns.

Hub API

The Scion Hub provides a RESTful API (mostly JSON) for managing the state of the system.

Authentication

Most endpoints require a Bearer token in the Authorization header.

• User Tokens: Obtained via OAuth or Dev Auth.
• Agent Tokens: Issued to agents at startup for state reporting.
• Broker Tokens: Used for broker-to-hub communication, often combined with HMAC request signing.

Core Resources

Agents (/api/v1/agents)

• GET /: List agents (filterable by project, user, phase).
• POST /: Dispatch a new agent.
• GET /:id: Get detailed agent state (phase, activity, detail).
• POST /:id/suspend: Suspend a running agent, preserving its harness session for a later resume. Sets the phase to suspended. Requires a harness that supports session resume.
• POST /:id/start, POST /:id/restart: Start/restart an agent. Starting a suspended agent resumes (continues) its harness session; starting a stopped or error agent runs a fresh session.
• DELETE /:id: Stop and remove an agent.
• GET /:id/logs: Stream agent logs (WebSocket).

There is no separate resume endpoint: resuming is the start action applied to a suspended agent. A suspended agent is also resumed automatically when a message is delivered to it with the wake option set.

Agent state uses a layered model:

• Phase: Lifecycle stage (created, provisioning, cloning, starting, running, stopping, stopped), plus suspended (paused for resume) and error (the agent crashed — restartable).
• Activity: Runtime activity within the running phase (working, thinking, executing, waiting_for_input, blocked, completed, limits_exceeded, stalled, offline). Note: offline occurs when an agent heartbeat has not been heard for some time, often due to an expired auth token that the agent failed to refresh; stalled flags a live-but-hung agent and can trigger auto-suspend. (A crash surfaces as the error phase, not as an activity.)
• Detail: Freeform context (tool name, message, task summary).

Projects (/api/v1/projects)

• GET /: List projects you have access to.
• POST /register: Register or link a project repository.
• GET /:id: Get project metadata and statistics.
• GET /:id/secrets: Manage environment secrets for the project.

Runtime Brokers (/api/v1/brokers)

• GET /: List registered runtime brokers.
• POST /register: Register a new compute node.
• POST /join: Complete the two-phase broker registration.
• GET /:id: Get broker status and capacity.

Templates (/api/v1/templates)

• GET /: List available agent templates.
• POST /: Upload a new template or version.

Runtime Broker API

The Runtime Broker exposes a local API (usually on port 9800) for agent execution and management.

Control Channel (WebSocket)

Brokers maintain a persistent outbound WebSocket connection to the Hub. The Hub uses this tunnel to send commands (e.g., CreateAgent) to brokers that might be behind NAT.

Local Endpoints

• GET /healthz: Basic liveness and readiness check.
• POST /api/v1/agents: (Internal) The Hub dispatches agents to this endpoint.
• GET /api/v1/agents/:id/attach: (WebSocket) Provides a terminal stream for interactive sessions.

Communication Patterns

State Reporting

Agents use the sciontool utility to report their state back to the Hub via the POST /api/v1/agents/:id/status endpoint. State updates include the agent’s current phase, activity, and contextual detail (e.g., which tool is executing). This happens at high frequency during task execution.

Log Streaming

Logs are collected by the Runtime Broker and can be streamed in two ways:

1. Real-time: Streamed via WebSocket from the Broker to the Hub, then to the Dashboard/CLI.
2. Persistent: Batched and uploaded to a storage backend (like GCS) after agent completion.