Subako Public API

The public HTTP interface to Subako.

Every request carries a bearer credential, and the organization it acts in is the credential’s – no path names one. Work resources belong to a workspace, named by the Kikuvi-Workspace header where a user credential cannot imply one.

Listings are cursor paged: pass the next_cursor a page returns back as after, and order decides which way the walk continues. Writes that create something accept an Idempotency-Key, and a retry under the same key returns the saved receipt rather than acting twice.

agents

The named lines a session runs, and the immutable versions that carry their config.

• GET
  List agents/v1/agents
• POST
  Create an agent/v1/agents
• GET
  Get an agent/v1/agents/{agent_id}
• DELETE
  Delete an agent/v1/agents/{agent_id}
• PATCH
  Rename an agent/v1/agents/{agent_id}
• GET
  Get an agent's security document/v1/agents/{agent_id}/security
• PUT
  Replace an agent's security document/v1/agents/{agent_id}/security
• GET
  List an agent's versions/v1/agents/{agent_id}/versions
• POST
  Publish an agent version/v1/agents/{agent_id}/versions

api-keys

Long-lived credentials for a backend, scoped to one workspace and the permissions they were minted with.

• GET
  List API keys/v1/api-keys
• POST
  Mint an API key/v1/api-keys
• DELETE
  Revoke an API key/v1/api-keys/{api_key_id}

me

Who the presented credential belongs to.

• GET
  Get the authenticated caller/v1/me

model-providers

Where model calls are sent: a platform provider Subako publishes, or one bound to your own key.

• GET
  List model providers/v1/model-providers
• POST
  Create a model provider/v1/model-providers
• GET
  Get a model provider/v1/model-providers/{model_provider_id}
• DELETE
  Delete a model provider/v1/model-providers/{model_provider_id}
• PATCH
  Update a model provider/v1/model-providers/{model_provider_id}

organization

The tenant a credential acts in: its members, its invitations, and what it has spent.

• GET
  Get the organization/v1/organization
• PATCH
  Rename the organization/v1/organization
• GET
  Get the credit balance/v1/organization/credits
• GET
  List invitations/v1/organization/invitations
• POST
  Invite a user/v1/organization/invitations
• DELETE
  Revoke an invitation/v1/organization/invitations/{invitation_id}
• GET
  List organization members/v1/organization/members
• PUT
  Change a member's role/v1/organization/members/{user_id}
• DELETE
  Remove a member/v1/organization/members/{user_id}
• GET
  List organization usage/v1/organization/usage

sessions

One agent version running against one event log: its input, its transcript, its sandboxes, and its tokens.

• GET
  List sessions/v1/sessions
• POST
  Create a session/v1/sessions
• GET
  Get a session/v1/sessions/{session_id}
• DELETE
  Delete a session/v1/sessions/{session_id}
• POST
  Resolve an approval/v1/sessions/{session_id}/approvals/{call_id}
• POST
  Cancel the active run/v1/sessions/{session_id}/cancel
• GET
  List session events/v1/sessions/{session_id}/events
• POST
  Send input to a session/v1/sessions/{session_id}/events
• GET
  Stream session events/v1/sessions/{session_id}/events/stream
• GET
  List a session's sandboxes/v1/sessions/{session_id}/sandboxes
• GET
  Get a sandbox archive download/v1/sessions/{session_id}/sandboxes/{name}/archive
• DELETE
  Delete a sandbox archive/v1/sessions/{session_id}/sandboxes/{name}/archive
• POST
  Mint a session token/v1/sessions/{session_id}/tokens

clients

A client offers tools of its own to a session’s agent, and answers the calls the model makes to them.

• POST
  Register a client/v1/sessions/{session_id}/clients
• DELETE
  Unregister a client/v1/sessions/{session_id}/clients/{client_id}
• POST
  Acknowledge a tool call/v1/sessions/{session_id}/clients/{client_id}/calls/{call_id}/ack
• POST
  Answer a tool call/v1/sessions/{session_id}/clients/{client_id}/calls/{call_id}/result
• POST
  Keep a client registration alive/v1/sessions/{session_id}/clients/{client_id}/ping
• PUT
  Replace a client's tools/v1/sessions/{session_id}/clients/{client_id}/tools

skills

Versioned bundles an agent may be granted.

• GET
  List skills/v1/skills
• POST
  Create a skill/v1/skills
• GET
  Get a skill/v1/skills/{skill_id}
• DELETE
  Delete a skill/v1/skills/{skill_id}
• PATCH
  Rename a skill/v1/skills/{skill_id}
• GET
  List a skill's versions/v1/skills/{skill_id}/versions
• POST
  Push a skill version/v1/skills/{skill_id}/versions

vaults

Credentials an agent presents to the services it reaches. A payload goes in and never comes back out.

• GET
  List vaults/v1/vaults
• POST
  Create a vault/v1/vaults
• GET
  Get a vault/v1/vaults/{vault_id}
• DELETE
  Delete a vault/v1/vaults/{vault_id}
• PATCH
  Update a vault/v1/vaults/{vault_id}
• GET
  List credentials/v1/vaults/{vault_id}/credentials
• POST
  Add a credential/v1/vaults/{vault_id}/credentials
• DELETE
  Delete a credential/v1/vaults/{vault_id}/credentials/{credential_id}

workspaces

The scope every work resource belongs to, and who may reach it.

• GET
  List workspaces/v1/workspaces
• POST
  Create a workspace/v1/workspaces
• GET
  Get a workspace/v1/workspaces/{workspace_id}
• DELETE
  Delete a workspace/v1/workspaces/{workspace_id}
• PATCH
  Rename a workspace/v1/workspaces/{workspace_id}
• GET
  List workspace members/v1/workspaces/{workspace_id}/members
• POST
  Add a workspace member/v1/workspaces/{workspace_id}/members
• PUT
  Change a workspace member's role/v1/workspaces/{workspace_id}/members/{user_id}
• DELETE
  Remove a workspace member/v1/workspaces/{workspace_id}/members/{user_id}
• GET
  List workspace usage/v1/workspaces/{workspace_id}/usage