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; pass its prev_cursor back as before to step back. 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}

functions

Versioned WebAssembly packages whose functions an agent may be granted as tools.

• GET
  List function packages/v1/functions
• POST
  Create a function package/v1/functions
• GET
  List the platform function packages/v1/functions/platform
• GET
  Get a function package/v1/functions/{function_id}
• DELETE
  Delete a function package/v1/functions/{function_id}
• PATCH
  Rename a function package/v1/functions/{function_id}
• GET
  List a function package's versions/v1/functions/{function_id}/versions
• POST
  Push a function package version/v1/functions/{function_id}/versions
• GET
  Get a function package version/v1/functions/{function_id}/versions/{version}

me

Who the presented credential belongs to.

• GET
  Get the authenticated caller/v1/me
• PATCH
  Rename 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}

oauth-clients

Your own OAuth clients at providers, which a vault connects credentials through. A secret goes in and never comes back out.

• GET
  List OAuth clients/v1/oauth-clients
• POST
  Create an OAuth client/v1/oauth-clients
• GET
  Get an OAuth client/v1/oauth-clients/{oauth_client_id}
• DELETE
  Delete an OAuth client/v1/oauth-clients/{oauth_client_id}
• PATCH
  Update an OAuth client/v1/oauth-clients/{oauth_client_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
  Get the organization's plan/v1/organization/plan
• GET
  List organization usage/v1/organization/usage
• GET
  List the plans/v1/plans

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}
• PATCH
  Rename 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
  Download a session image/v1/sessions/{session_id}/images/{sha256}
• POST
  Answer a form/v1/sessions/{session_id}/inputs/{call_id}
• 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
• DELETE
  Delete a session tree's volume files/v1/sessions/{session_id}/volume
• GET
  List a session tree's volume files/v1/sessions/{session_id}/volume/{area}
• GET
  Download a volume file/v1/sessions/{session_id}/volume/{area}/{path}
• PUT
  Upload a volume file/v1/sessions/{session_id}/volume/{area}/{path}
• DELETE
  Delete a volume file/v1/sessions/{session_id}/volume/{area}/{path}

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
• GET
  Get a skill version/v1/skills/{skill_id}/versions/{version}
• GET
  Get a skill version's bundle download/v1/skills/{skill_id}/versions/{version}/bundle

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
• POST
  Start connecting a credential through OAuth/v1/vaults/{vault_id}/credentials/oauth
• POST
  Complete connecting a credential through OAuth/v1/vaults/{vault_id}/credentials/oauth/complete
• DELETE
  Delete a credential/v1/vaults/{vault_id}/credentials/{credential_id}
• POST
  Check a credential against its server/v1/vaults/{vault_id}/credentials/{credential_id}/check
• POST
  Start reconnecting an OAuth credential/v1/vaults/{vault_id}/credentials/{credential_id}/oauth

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
• GET
  Get the workspace's usage report/v1/workspaces/{workspace_id}/usage-report