Overview

HTTP API for the Evershell control plane

Evershell Control Plane API 1.0

The Evershell control plane exposes a JSON HTTP API covering every resource a customer manages: providers, agent roles, content packs, workspaces, tasks, credentials, secrets, API keys, memberships, and the audit log.

Base URL — https://<your-slug>.evershell.ai/v1

Authentication — Every request must carry a bearer token. The middleware accepts three credential shapes, picked by intrinsic prefix:

Session JWT (eyJ...) — issued by AuthKit on browser sign-in.
API key (sk_...) — issued from Settings → API keys; the automation path. See API keys for the lifecycle, permission templates, and verify path.
wos_session cookie — set automatically by /auth/callback for console pages.

For SSE consumers that can’t set headers, API keys may also be presented as ?api_key=sk_... in the query string. Session JWTs are never accepted in the query string.

Permissions — Each operation below carries a Permissions: line declaring which scope(s) the caller must hold. Scope names follow the <resource>:<verb>[:own] pattern; :own narrows the scope to caller-owned resources. The permissions reference explains each scope and which routes it gates; the member-roles page shows which scopes Owner / Operator / Member hold by default. A request that doesn’t carry any of the required scopes returns 403 permission_denied; the console hides anything the caller can’t reach.

Billing posture — Mutating routes split into two groups:

Create-class (POST / PUT / PATCH that add or amend resources): require an active billing posture (active or non-expired trial). Any other posture — past_due, decommissioning, expired trial — returns 423 billing_inactive. These responses are documented per route below.
Wind-down (DELETE, archive, stop, cancel): reachable from any known billing posture, so a customer in past_due or decommissioning can still remove resources and halt in-flight work. No 423 on these routes.

Reads (GET) never 423 — observability stays available regardless of billing posture.

Error envelope — Every error response uses the same shape: { "error": { "code": "...", "message": "...", "request_id": "...", "details": { ... } } }.

Information

OpenAPI version: 3.1.0

Authentication

bearerAuth

Bearer token in Authorization: Bearer <token>. Accepts both session JWTs (eyJ...) and API keys (sk_...).

Security scheme type: http

Overview

Evershell Control Plane API 1.0

Operations

Authentication

bearerAuth