api

README

satelle hosted API

Conformance specification for the satelle hosted server interface. The CLI publishes this; servers in any language implement it with their own types (verified by contract tests on the server side). No shared Go module exists — the OpenAPI spec is the canonical definition.

Auth conventions

Scheme: Bearer token (Authorization: Bearer <access_token>)

Tokens are obtained via OAuth 2.1 + PKCE S256:

1. Browser redirect to GET /oauth/authorize with response_type=code, client_id, redirect_uri, state, code_challenge, code_challenge_method=S256.
2. On approval the server redirects back with code and state.
3. POST /oauth/token with grant_type=authorization_code, code, redirect_uri, client_id, code_verifier (form-encoded).

Refresh: On a 401, clients should attempt a refresh_token grant (grant_type=refresh_token + refresh_token + client_id) and retry the original request once.

Endpoints

GET /api/v1/me

Returns the authenticated principal.

Response 200: Principal

Field	Type	Description
id	string	Unique principal identifier
email	string
display_name	string
role	string	e.g. admin, member

GET /api/v1/projects

Returns all projects the caller is a member of.

Response 200: array of Project

Field	Type	Description
id	string	Unique project identifier
slug	string	URL-safe slug (unique per server)
name	string
role	string	Caller's role (may be omitted)

POST /api/v1/projects

Creates a new project. The authenticated principal becomes owner.

Request body: CreateProjectRequest

Field	Type	Description
slug	string	URL-safe slug (must be unique)
name	string

Response 201: Project
Response 409: Slug already exists.

GET /oauth/authorize

Browser redirect to initiate OAuth 2.1 + PKCE S256. No bearer token required.

Query parameters:

Parameter	Type	Description
response_type	string	Must be code
client_id	string	Public client identifier
redirect_uri	string	Callback URI
state	string	CSRF token (echoed back)
code_challenge	string	PKCE S256 challenge
code_challenge_method	string	Must be S256

Response 302: Redirect to redirect_uri with code + state (approval) or error + error_description (denial).

POST /oauth/token

Exchanges an authorization code or refreshes tokens. No bearer token required.

Request: application/x-www-form-urlencoded

Parameter	Type	Description
grant_type	string	authorization_code or refresh_token
client_id	string	Public client identifier
code	string	Auth code (authorization_code grant)
redirect_uri	string	Redirect URI (authorization_code grant)
code_verifier	string	PKCE S256 verifier (authorization_code grant)
refresh_token	string	Refresh token (refresh_token grant)

Response 200: TokenResponse

Field	Type	Description
access_token	string	Bearer access token
refresh_token	string	Refresh token
token_type	string	e.g. Bearer
expires_in	int64	Lifetime in seconds
scope	string	Granted scope(s)

Response 400: OAuthError

Field	Type	Description
error	string	OAuth error code
error_description	string	Human-readable detail

Error envelope

All API endpoints (except OAuth) use a consistent JSON error body:

{"error": "not_found", "message": "project does not exist"}

Field	Type	Description
error	string	Machine-readable error code
message	string	Human-readable detail

HTTP status codes

Code	Meaning
200	Success
201	Created
400	Invalid request / OAuth error
401	Authentication required
403	Forbidden (insufficient role)
404	Not found
409	Conflict (slug already exists)

Reference types

The Go reference wire types live in types.go. They are structurally identical to the CLI's internal client types but independently owned — no cross-imports between api/ and internal/.

Documentation

Overview

Package api provides reference wire types for the satelle hosted API.

Servers in any language implement these shapes; the OpenAPI spec (openapi.yaml) is the canonical interface definition. This package is a standalone reference — it does not import internal/hosted, and the internal client types are structurally identical but independently owned.

Index

• type ConfigItem
• type ConfigPushResult
• type ConfigRollbackRequest
• type CreateProjectRequest
• type DocumentChanges
• type ErrorEnvelope
• type OAuthError
• type Principal
• type Project
• type PublishedItem
• type TokenResponse
• type Workspace
• type WorkstateIngest
• type WorkstateIngestResult
• type WorkstateItem
• type WorkstateLedgerRow

Types

type ConfigItem

type ConfigItem struct {
	Path       string `json:"path"`
	Version    int    `json:"version"`
	BlobSHA256 string `json:"blob_sha256"`
	Size       int64  `json:"size"`
	CreatedAt  string `json:"created_at"`
}

ConfigItem is one entry in a workspace's config manifest — the deploy set for "set up project X like project Y". It is the latest head of a config path in a workspace, returned by GET /api/v1/workspaces/{id}/config.

type ConfigPushResult

type ConfigPushResult struct {
	Path       string `json:"path"`
	Version    int    `json:"version"`
	BlobSHA256 string `json:"blob_sha256"`
	Size       int64  `json:"size"`
	Created    bool   `json:"created"`
}

ConfigPushResult is the per-file response to PUT /api/v1/workspaces/{id}/config/{path}. Created is true when the push appended a new head (HTTP 201) and false when it was an idempotent re-push of the current head (HTTP 200) — the per-file idempotency signal.

type ConfigRollbackRequest

type ConfigRollbackRequest struct {
	Path    string `json:"path"`
	Version int    `json:"version"`
}

ConfigRollbackRequest is the body for POST /api/v1/workspaces/{id}/config-rollback: append a new head copying an earlier version of a path (recovery of a prior version).

type CreateProjectRequest

type CreateProjectRequest struct {
	Slug string `json:"slug"`
	Name string `json:"name"`
}

CreateProjectRequest is the JSON body for POST /api/v1/projects.

type DocumentChanges

type DocumentChanges struct {
	Items  []ConfigItem `json:"items"`
	Cursor string       `json:"cursor"`
}

DocumentChanges is the response to GET /api/v1/workspaces/{id}/documents (optionally ?since=<cursor>): the items that changed after the caller's cursor, plus the new cursor for the next incremental pull. Item shape reuses ConfigItem (path/version/blob_sha256/size/created_at) — same per-file head metadata as the config store.

type ErrorEnvelope

type ErrorEnvelope struct {
	Error   string `json:"error"`
	Message string `json:"message"`
}

ErrorEnvelope is the standard JSON error body returned by API endpoints.

type OAuthError

type OAuthError struct {
	Code        string `json:"error"`
	Description string `json:"error_description"`
}

OAuthError is the /oauth/token error body ({"error","error_description"}).

type Principal

type Principal struct {
	ID          string `json:"id"`
	Email       string `json:"email"`
	DisplayName string `json:"display_name"`
	Role        string `json:"role"`
}

Principal is the identity returned by GET /api/v1/me.

type Project

type Project struct {
	ID   string `json:"id"`
	Slug string `json:"slug"`
	Name string `json:"name"`
	Role string `json:"role,omitempty"`
}

Project is a hosted project as returned by the projects API. Role is only populated by responses that carry the caller's membership.

type PublishedItem

type PublishedItem struct {
	Path        string `json:"path"`
	Kind        string `json:"kind"`
	Version     int    `json:"version"`
	BlobSHA256  string `json:"blob_sha256"`
	Size        int64  `json:"size"`
	PublisherID string `json:"publisher_id"`
	Title       string `json:"title"`
	CreatedAt   string `json:"created_at"`
	Created     bool   `json:"created,omitempty"`
}

PublishedItem is one head (or history entry) in a team workspace's publisher-owned catalog — GET /api/v1/workspaces/{id}/published (list), PUT /api/v1/workspaces/{id}/published/{path} (publish), and the metadata headers on GET …/published/{path} (content). Team catalog only; not a personal-sync destination (epic:sync-publish).

type TokenResponse

type TokenResponse struct {
	AccessToken  string `json:"access_token"`
	RefreshToken string `json:"refresh_token"`
	TokenType    string `json:"token_type"`
	ExpiresIn    int64  `json:"expires_in"`
	Scope        string `json:"scope"`
}

TokenResponse is the /oauth/token success body (authorization_code and refresh_token grants).

type Workspace

type Workspace struct {
	ID   string `json:"id"`
	Kind string `json:"kind"`
	Name string `json:"name"`
}

Workspace is a hosted workspace as returned by the workspaces API. Kind is "personal" (the caller's own workspace) or "team" (a shared/team workspace). The server returns no slug; clients identify a workspace by name or id.

type WorkstateIngest

type WorkstateIngest struct {
	Items  []json.RawMessage `json:"items"`
	Ledger []json.RawMessage `json:"ledger"`
}

WorkstateIngest is the POST body for /api/v1/workspaces/{id}/workstate — a local→server batch of stories/executions (items) and ledger entries. The server stamps origin=cli-sync; the client never supplies origin. Pull uses GET …/workstate/items and GET …/workstate/ledger (rehydrate).

type WorkstateIngestResult

type WorkstateIngestResult struct {
	Items  int `json:"items"`
	Ledger int `json:"ledger"`
}

WorkstateIngestResult is the POST response: counts of upserted rows.

type WorkstateItem

type WorkstateItem struct {
	ID     string          `json:"id"`
	Kind   string          `json:"kind"`
	Type   string          `json:"type"`
	Status string          `json:"status"`
	Title  string          `json:"title"`
	Origin string          `json:"origin"`
	Record json.RawMessage `json:"record"`
}

WorkstateItem is one row from GET …/workstate/items (mirror list for pull).

type WorkstateLedgerRow

type WorkstateLedgerRow struct {
	ID      string          `json:"id"`
	StoryID string          `json:"story_id"`
	Kind    string          `json:"kind"`
	Type    string          `json:"type"`
	Origin  string          `json:"origin"`
	Record  json.RawMessage `json:"record"`
}

WorkstateLedgerRow is one row from GET …/workstate/ledger.