Skip to main content
API docs by Redocly

Bossanova Orchestrator API (2026-07-11)

Download OpenAPI specification:Download

License: Proprietary

OpenAPI reference for the bossanova.v1 OrchestratorService, the Connect API served by bosso. Callers select a date-based API version with the Bossanova-Version request header; see the API changelog for version history.

bossanova.v1.OrchestratorService

OrchestratorService is the cloud-hosted service that coordinates multiple daemons, provides remote CLI access, and handles webhook routing.

CompleteGitHubAppSetup

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
installationId
integer or string <int64> (installation_id)
state
string (state)

Server-issued setup state returned by GetGitHubAppInstallURL.

githubCode
string (github_code)

GitHub OAuth code returned by the GitHub App setup callback. Exchanged once for a user access token to verify the caller can access installation_id.

Responses

Request samples

Content type
application/json
{
  • "installationId": 0,
  • "state": "string",
  • "githubCode": "string"
}

Response samples

Content type
application/json
{
  • "repos": [
    ]
}

CreateBillingPortalSession

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
returnUrl
string (return_url)

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "string"
}

Response samples

Content type
application/json
{
  • "url": "string"
}

CreateCheckoutSession

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
returnUrl
string (return_url)
cancelUrl
string (cancel_url)

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "string",
  • "cancelUrl": "string"
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "status": {
    }
}

CreateWebhookConfig

Webhook configuration management

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
repoOriginUrl
string (repo_origin_url)
provider
string (provider)
secret
string (secret)

If empty, a random secret will be generated.

Responses

Request samples

Content type
application/json
{
  • "repoOriginUrl": "string",
  • "provider": "string",
  • "secret": "string"
}

Response samples

Content type
application/json
{
  • "config": {
    }
}

DeleteWebhookConfig

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{ }

DisconnectGitHubAppRepo

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
repoOriginUrl
string (repo_origin_url)

Responses

Request samples

Content type
application/json
{
  • "repoOriginUrl": "string"
}

Response samples

Content type
application/json
{ }

GetCloudAccessStatus

Cloud billing and access. User-authenticated.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (GetCloudAccessStatusRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": {
    }
}

GetGitHubAppInstallURL

GitHub App repository registration. User-authenticated.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
returnUrl
string (return_url)

Optional absolute URL to return to after GitHub setup. Empty uses bosso default.

Responses

Request samples

Content type
application/json
{
  • "returnUrl": "string"
}

Response samples

Content type
application/json
{
  • "installUrl": "string"
}

IssueAttachToken

IssueAttachToken returns a short-lived JWT bound to (user, session, chat, scope) that the browser uses to authenticate the /ws/attach WebSocket handshake. TTL ~5 minutes.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)
chatId
string (chat_id)
scope
string (bossanova.v1.AttachScope)
Enum: "ATTACH_SCOPE_UNSPECIFIED" "ATTACH_SCOPE_EDITOR" "ATTACH_SCOPE_VIEWER"

EDITOR or VIEWER. Only EDITOR is used in v1 — VIEWER is accepted and behaves identically for now (see the plan's deferred items).

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "chatId": "string",
  • "scope": "ATTACH_SCOPE_UNSPECIFIED"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "expiresAt": "2023-01-15T01:30:15.01Z"
}

ListDaemons

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (ListDaemonsRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "daemons": [
    ]
}

ListGitHubAppRepos

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (ListGitHubAppReposRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "repos": [
    ]
}

ListWebhookConfigs

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (ListWebhookConfigsRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "configs": [
    ]
}

ProxyArchiveSession

Archives a session via the owning daemon's reverse stream.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

ProxyDeleteChat

Deletes a chat via the owning daemon's reverse stream.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)

for authz scoping (mirror ProxyWakeChat)

agentSessionId
string (agent_session_id)

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "agentSessionId": "string"
}

Response samples

Content type
application/json
{ }

ProxyGetChatTranscript

Reads a chat's transcript via the owning daemon's reverse stream. Routes by session_id (FindSessionDaemon) with a GetChat authz check, like ProxyWakeChat.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)

for authz scoping (mirror ProxyWakeChat)

agentSessionId
string (agent_session_id)
maxMessages
integer <int32> (max_messages)

0 = all; otherwise the most recent N

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "agentSessionId": "string",
  • "maxMessages": 0
}

Response samples

Content type
application/json
{
  • "messages": [
    ],
  • "finalAssistantText": "string",
  • "exists": true,
  • "reason": "string"
}

ProxyGetSession

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

ProxyListAccounts

Lists the rotation accounts on the daemon owning session_id (web account-switch picker). Routes by session_id (FindSessionDaemon) for authz scope, like ProxySwitchSessionAccount. Accounts are metadata only — never credentials. Optional provider filter ("" = all).

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)
provider
string (provider)

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "provider": "string"
}

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

ProxyListAgents

Lists the installed agents on a single named daemon via its reverse stream.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
daemonId
string (daemon_id)

Responses

Request samples

Content type
application/json
{
  • "daemonId": "string"
}

Response samples

Content type
application/json
{
  • "agents": [
    ]
}

ProxyListRepoPRs

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
daemonId
string (daemon_id)
repoId
string (repo_id)

Responses

Request samples

Content type
application/json
{
  • "daemonId": "string",
  • "repoId": "string"
}

Response samples

Content type
application/json
{
  • "pullRequests": [
    ]
}

ProxyListReposAggregated

Aggregates repos across all of the caller's live daemons, deduped by origin URL, with the serving daemon IDs unioned per repo.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (ProxyListReposAggregatedRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "repos": [
    ]
}

ProxyListSessions

Proxied daemon RPCs (remote CLI → orchestrator → daemon)

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
repoId
string or null (repo_id)
states
Array of strings (states)
Items Enum: "SESSION_STATE_UNSPECIFIED" "SESSION_STATE_CREATING_WORKTREE" "SESSION_STATE_STARTING_AGENT" "SESSION_STATE_PUSHING_BRANCH" "SESSION_STATE_OPENING_DRAFT_PR" "SESSION_STATE_IMPLEMENTING_PLAN" "SESSION_STATE_AWAITING_CHECKS" "SESSION_STATE_FIXING_CHECKS" "SESSION_STATE_GREEN_DRAFT" "SESSION_STATE_READY_FOR_REVIEW" "SESSION_STATE_BLOCKED" "SESSION_STATE_MERGED" "SESSION_STATE_CLOSED" "SESSION_STATE_FINALIZING" "SESSION_STATE_ORPHANED"
includeArchived
boolean (include_archived)
daemonId
string or null (daemon_id)

Target daemon, if known. Otherwise orchestrator queries all.

Responses

Request samples

Content type
application/json
{
  • "repoId": "string",
  • "states": [
    ],
  • "includeArchived": true,
  • "daemonId": "string"
}

Response samples

Content type
application/json
{
  • "sessions": [
    ]
}

ProxyListTrackerIssues

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
daemonId
string (daemon_id)
repoId
string (repo_id)
query
string (query)
source
string or null (source)

"linear" (default) | "sentry"

Responses

Request samples

Content type
application/json
{
  • "daemonId": "string",
  • "repoId": "string",
  • "query": "string",
  • "source": "string"
}

Response samples

Content type
application/json
{
  • "issues": [
    ]
}

ProxyMergeSession

Merges a session's PR via the owning daemon's reverse stream.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

ProxyPauseSession

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

ProxyRecordChat

Records or resumes a chat via the owning daemon's reverse stream.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)
agentSessionId
string (agent_session_id)
title
string (title)
resume
boolean (resume)
agentName
string (agent_name)

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "agentSessionId": "string",
  • "title": "string",
  • "resume": true,
  • "agentName": "string"
}

Response samples

Content type
application/json
{
  • "chat": {
    }
}

ProxyResumeSession

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

ProxySendChatMessage

Sends a user message into a chat via the owning daemon's reverse stream. Routes by agent_session_id (FindDaemonForChat) since the MCP send tool carries no session_id.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
agentSessionId
string (agent_session_id)
message
string (message)
wakeIfAsleep
boolean (wake_if_asleep)
submit
boolean or null (submit)

when true, submit the message (BOS-242); when false, prefill only. optional so an omitting (pre-BOS-242) client is treated as submit=true server-side, preserving the prior always-submit proxy behavior.

Responses

Request samples

Content type
application/json
{
  • "agentSessionId": "string",
  • "message": "string",
  • "wakeIfAsleep": true,
  • "submit": true
}

Response samples

Content type
application/json
{
  • "tmuxSessionName": "string",
  • "delivered": true,
  • "noticeText": "string"
}

ProxyStopSession

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
id
string (id)

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    }
}

ProxySwitchSessionAccount

Switches a session's live chat to a different account (stop+swap+resume) via the owning daemon's reverse stream. Routes by session_id (FindSessionDaemon) with an optional GetChat authz check, like ProxyWakeChat.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)

for authz scoping (mirror ProxyWakeChat)

agentSessionId
string (agent_session_id)

optional; empty => session's primary live chat

accountId
string (account_id)

"" = system default

force
boolean (force)

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "agentSessionId": "string",
  • "accountId": "string",
  • "force": true
}

Response samples

Content type
application/json
{
  • "resumed": true,
  • "targetLabel": "string",
  • "noticeText": "string"
}

ProxyWakeChat

Wakes a stopped chat's tmux+claude. Routes to the owning daemon via the reverse stream and waits for CommandResult{WakeChatResult}.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)
agentSessionId
string (agent_session_id)
forceFresh
boolean (force_fresh)

If true, the daemon will skip --resume even when a transcript exists.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "agentSessionId": "string",
  • "forceFresh": true
}

Response samples

Content type
application/json
{
  • "outcome": "OUTCOME_UNSPECIFIED",
  • "tmuxSessionName": "string",
  • "reason": "string"
}

PublishDaemonSnapshot

PublishDaemonSnapshot is a unary fallback for networks that proxy normal HTTPS but do not support Connect bidirectional streaming end-to-end. Daemons authenticate with their RegisterDaemon session token and publish the same snapshot shape used as the first DaemonStream event.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (bossanova.v1.DaemonSnapshot)

DaemonSnapshot is the required first event on every stream connect. It carries slim metadata only (IDs, state, timestamps, preview strings) — full chat transcripts are fetched on demand via AttachSessionCommand (decision #5).

daemonId
string (daemon_id)
hostname
string (hostname)
repoIds
Array of strings (repo_ids)
Array of objects (sessions)

Slim: no full transcripts, just session state + display fields.

Array of objects (chats)

Metadata only — see ClaudeChatMetadata.

Array of objects (statuses)

Live chat statuses keyed by agent_session_id (reuses ChatStatusEntry from daemon.proto).

Responses

Request samples

Content type
application/json
{
  • "snapshot": {
    }
}

Response samples

Content type
application/json
{ }

RefreshCloudEntitlements

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
object (RefreshCloudEntitlementsRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "status": {
    }
}

RegisterDaemon

Daemon registry

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
daemonId
string (daemon_id)
hostname
string (hostname)
repoIds
Array of strings (repo_ids)

Repos this daemon manages.

endpoint
string or null (endpoint)

Optional endpoint URL where the daemon's DaemonService is reachable. Required for proxy RPC support. Daemons behind NAT may omit this.

email
string (email)

User email from the WorkOS device code response. Used for JIT user creation when the user doesn't exist in the DB yet.

Responses

Request samples

Content type
application/json
{
  • "daemonId": "string",
  • "hostname": "string",
  • "repoIds": [
    ],
  • "endpoint": "string",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "daemonId": "string",
  • "sessionToken": "string"
}

ReportBug

Bug reporting (easter-egg ctrl+b in TUI). Unauthenticated; optionally resolves the caller's identity when a bearer token is present.

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
comment
string (comment)
object (bossanova.v1.ReportContext)

ReportContext bundles everything the TUI attaches to a bug report. All fields are optional; the server tolerates empty values.

Responses

Request samples

Content type
application/json
{
  • "comment": "string",
  • "context": {
    }
}

Response samples

Content type
application/json
{
  • "reportId": "string"
}

TransferSession

Session transfer between daemons

header Parameters
Connect-Protocol-Version
required
number (Connect-Protocol-Version)
Value: 1

Define the version of the Connect protocol

Value: 1
Connect-Timeout-Ms
number (Connect-Timeout-Ms)

Define the timeout, in ms

Request Body schema: application/json
required
sessionId
string (session_id)
sourceDaemonId
string (source_daemon_id)

Daemon to transfer FROM.

targetDaemonId
string (target_daemon_id)

Daemon to transfer TO.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "string",
  • "sourceDaemonId": "string",
  • "targetDaemonId": "string"
}

Response samples

Content type
application/json
{
  • "session": {
    },
  • "targetDaemonId": "string"
}