API Reference

OpenSeal serves a versioned REST API, executes a deterministic runbook layer defined in HCL, and is importable as a Go library. This page is the reference for all three.

REST Conventions

All routes are served under /api/v1 from the address in api.listenAddr. Responses are JSON. Errors return {"error": "<message>"}, except ClawHub lifecycle errors, which add a code field carrying a canonical error code.

Status Codes

Bearer authentication is optional. With OPENSEAL_API_TOKEN, every route requires Authorization: Bearer <token> and rejects missing or invalid tokens with 401. The token does not supply individual identity or per-scope authorization. See Security.

Reading the Capability Document First

A substantial part of this surface is conditional. Fifty-five distinct 501 responses exist across the handlers, each naming the component that is missing. Client code should branch on GET /api/v1/capabilities rather than assume a route exists — two daemons at the same version can present materially different surfaces. See Concepts.

Service

Objectives

Projects

Agent Runs and Turns

The commands route carries pause, resume, cancel, and intervene. The admission route reports why a Run would or would not be admitted, and is the first thing to check when a Run stays queued. See Objectives and Runs.

Agent Requests

Action Calls and Approvals

Action calls are read-only; they are created by the execution path. The decisions route requires an approval authorizer, which standalone mode installs only under --standalone-operator. See Skills and Approvals.

Agent Deployments

Team Definitions and Deployments

Agent deployments carry a direct rollback route; Team deployments do not. Otherwise the two lifecycles are identical. See Agents and Teams.

Skill Actions and Bindings

The upgrade-plan and upgrade routes are withdrawn from the advertised capability when the configured store does not implement the upgrade contract.

ClawHub

Read operations are always available once ClawHub is wired. Install, update, pin, unpin, and uninstall are filtered out unless mutation authority has been granted. These are the only routes that return a canonical code alongside the error message — see Skills and Approvals.

Artifacts

Upload and download require an artifact content store, which the daemon wires from storage.artifactsPath. Uploads are capped at 100 MiB and exceed it with 413.

Resolution requires a component the daemon does not wire. POST /api/v1/artifacts/{id}/resolve returns an ephemeral authorized URL rather than bytes, and needs a separate content resolver. In a standalone deployment it always returns 501 Not Implemented.

Conversations and Channels

Participation rounds are how multiple Agents take turns in one channel without talking over each other. Cursors record how far each participant has read; presence records who is currently attached.

Runbooks

Event Sources and Routing

Source Monitors and Outreach

Outreach is advertised only when the store implements the project, source monitor, outreach, and outreach action contracts together. Thread creation additionally requires a Skill catalog, and delivery additionally requires a wired dispatcher. Even under --standalone-operator, delivery is refused for any scope whose source policy does not enable outreach.

Source Policies

These routes manage the durable source-policy lifecycle, which is distinct from the static sourcePolicies list in the daemon configuration file.

All eight fail closed in a standalone deployment. They require a source-policy lifecycle service the standalone daemon does not install, so every one returns 501 Not Implemented. Configure source policies through the daemon configuration file instead — see Configuration.

Workforce Authoring

Workforce Bundles

The five read operations work in every deployment. Installation requires an installation store and a host-authenticated actor, which the bundled daemon does not supply, so POST /api/v1/workforce-bundles/install always returns 501 Not Implemented. See Workforces.

Deterministic Runbooks

Alongside the durable kernel, OpenSeal carries a deterministic runbook layer: a directed graph of typed nodes defined in HCL and executed in a single process by openseal run. It is a separate execution path — it creates no Runs, produces no activity events, and takes part in no approvals.

workflow "notify" {
  description = "Post a message when an endpoint responds"

  node http "fetch" {
    url = "https://example.com/status"
  }

  node slack "notify" {
    channel = "#ops"
  }

  edge "fetch" "notify" {
  }
}

Node metadata — display names, categories, and the input schemas used by openseal validate — lives in 28 YAML files under embedded_nodes/, with an identical copy under cmd/openseal/embedded_nodes/.

Node Types

The gap between node types that have metadata and node types that have a registered executor is the most important thing to know about this layer.

Twenty node types execute unconditionally. The code node registers only when an in-cluster Kubernetes client is available, and it runs Python in a job container.

Eight further Kubernetes node types — k8s_get, k8s_list, k8s_logs, k8s_events, k8s_restart, k8s_scale, k8s_patch, and k8s_delete — have complete executors but register only when a Kubernetes client is passed to the registry constructor. openseal run passes none, so they are never available from the CLI.

Trigger and tool nodes both lack a registered executor, and the two do not behave alike. A trigger node — webhook, cron, or manual — is handled before the executor lookup: it emits its data payload to the nodes downstream and execution continues, so a runbook whose first node is a trigger runs normally. A tool node has no such handling and stops the run with no executor registered for step type. Both categories describe nodes an embedding host is expected to supply. See CLI.

Go Embedding

github.com/axiom-studio/openseal/pkg/openseal is the supported facade. Packages under internal/ are not importable from outside the module, and the other pkg/ packages are implementation surfaces that the facade re-exports.

store, err := openseal.NewSQLiteStore("openseal.db")
if err != nil {
    return err
}
defer store.Close()

engine, err := openseal.New(openseal.WithPersistentStore(store))
if err != nil {
    return err
}
engine.Start(ctx)
defer engine.Stop()

An engine constructed with no store option uses an in-memory store, which is appropriate for tests and nothing else. Durable work requires an explicit persistent store.

Store Constructors

PostgreSQL store options: WithPostgresSchema, WithPostgresPool, WithPostgresMigrationLock, and WithPostgresMigrationObserver. Defaults and limits are in Operations.

Engine Options

The management-action options are what let an Agent operate the kernel itself — register a Skill, propose an amendment, command a Run — through the same governed action path as any other Skill.

The HTTP Client

pkg/client provides a client for programs that talk to a remote daemon rather than embedding the engine.

kernel := client.NewKernelHTTPClient("http://127.0.0.1:8080", nil)

NewKernelHTTPClient(baseURL, httpClient, options...) accepts an origin or an explicit API root and defaults to a thirty-second timeout. WithRequestHeaders adds headers to every request, silently dropping Content-Type and Idempotency-Key. Failures surface as an APIError carrying the status code and the server's message.

Next Steps

• Understand why the surface is conditional in Concepts.
• Read the exposure model before serving this API in Security.
• Operate a deployment using Operations.