Create and manage multi-tenant workspaces, invite and manage users and roles, and administer service accounts and their API keys for programmatic access and IAM.
openapi: 3.0.1
info:
title: Blaxel Control Plane API
description: >-
Representative specification of the Blaxel (formerly Beamlit) control plane
REST API. The control plane manages agents, MCP/function servers, models,
sandboxes, jobs, policies, integrations, and workspaces. Authenticate with a
Bearer API key (Authorization or X-Blaxel-Authorization header) or an OAuth
2.0 short-lived JWT. Requests may include a Blaxel-Version header
(YYYY-MM-DD) and, for multi-workspace accounts, an X-Blaxel-Workspace header.
termsOfService: https://blaxel.ai/terms-of-service
contact:
name: Blaxel Support
email: support@blaxel.ai
version: 'v0'
servers:
- url: https://api.blaxel.ai/v0
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Agents
- name: Functions
- name: Models
- name: Compute
- name: Jobs
- name: Policies
- name: Integrations
- name: Workspaces
- name: Service Accounts
- name: Volumes
- name: Locations
paths:
/agents:
get:
operationId: listAgents
tags: [Agents]
summary: List all agents in the workspace.
responses:
'200':
description: A list of agents.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Agent'
post:
operationId: createAgent
tags: [Agents]
summary: Create a new agent deployment.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
responses:
'200':
description: The created agent.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
/agents/{agent_name}:
parameters:
- $ref: '#/components/parameters/AgentName'
get:
operationId: getAgent
tags: [Agents]
summary: Get an agent by name.
responses:
'200':
description: The requested agent.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
put:
operationId: updateAgent
tags: [Agents]
summary: Update an agent by name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
responses:
'200':
description: The updated agent.
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
delete:
operationId: deleteAgent
tags: [Agents]
summary: Delete an agent by name.
responses:
'200':
description: The deleted agent.
/agents/{agent_name}/revisions:
parameters:
- $ref: '#/components/parameters/AgentName'
get:
operationId: listAgentRevisions
tags: [Agents]
summary: List revisions for an agent.
responses:
'200':
description: A list of agent revisions.
/functions:
get:
operationId: listFunctions
tags: [Functions]
summary: List all functions (MCP servers) in the workspace.
responses:
'200':
description: A list of functions.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Function'
post:
operationId: createFunction
tags: [Functions]
summary: Create a new function (MCP server).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
responses:
'200':
description: The created function.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
/functions/{function_name}:
parameters:
- $ref: '#/components/parameters/FunctionName'
get:
operationId: getFunction
tags: [Functions]
summary: Get a function by name.
responses:
'200':
description: The requested function.
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
put:
operationId: updateFunction
tags: [Functions]
summary: Update a function by name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Function'
responses:
'200':
description: The updated function.
delete:
operationId: deleteFunction
tags: [Functions]
summary: Delete a function by name.
responses:
'200':
description: The deleted function.
/functions/{function_name}/revisions:
parameters:
- $ref: '#/components/parameters/FunctionName'
get:
operationId: listFunctionRevisions
tags: [Functions]
summary: List revisions for a function.
responses:
'200':
description: A list of function revisions.
/models:
get:
operationId: listModels
tags: [Models]
summary: List all model deployments in the workspace.
responses:
'200':
description: A list of models.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Model'
post:
operationId: createModel
tags: [Models]
summary: Create a new model deployment behind the model gateway.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
responses:
'200':
description: The created model.
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
/models/{model_name}:
parameters:
- $ref: '#/components/parameters/ModelName'
get:
operationId: getModel
tags: [Models]
summary: Get a model by name.
responses:
'200':
description: The requested model.
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
put:
operationId: updateModel
tags: [Models]
summary: Update a model by name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
responses:
'200':
description: The updated model.
delete:
operationId: deleteModel
tags: [Models]
summary: Delete a model by name.
responses:
'200':
description: The deleted model.
/models/{model_name}/revisions:
parameters:
- $ref: '#/components/parameters/ModelName'
get:
operationId: listModelRevisions
tags: [Models]
summary: List revisions for a model.
responses:
'200':
description: A list of model revisions.
/sandboxes:
get:
operationId: listSandboxes
tags: [Compute]
summary: List all sandboxes in the workspace.
responses:
'200':
description: A list of sandboxes.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Sandbox'
post:
operationId: createSandbox
tags: [Compute]
summary: Create a new sandbox.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Sandbox'
responses:
'200':
description: The created sandbox.
content:
application/json:
schema:
$ref: '#/components/schemas/Sandbox'
/sandboxes/{sandbox_name}:
parameters:
- $ref: '#/components/parameters/SandboxName'
get:
operationId: getSandbox
tags: [Compute]
summary: Get a sandbox by name.
responses:
'200':
description: The requested sandbox.
content:
application/json:
schema:
$ref: '#/components/schemas/Sandbox'
put:
operationId: updateSandbox
tags: [Compute]
summary: Update a sandbox by name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Sandbox'
responses:
'200':
description: The updated sandbox.
delete:
operationId: deleteSandbox
tags: [Compute]
summary: Delete a sandbox by name.
responses:
'200':
description: The deleted sandbox.
/sandboxes/{sandbox_name}/start:
parameters:
- $ref: '#/components/parameters/SandboxName'
post:
operationId: startSandbox
tags: [Compute]
summary: Start a sandbox.
responses:
'200':
description: The started sandbox.
/sandboxes/{sandbox_name}/stop:
parameters:
- $ref: '#/components/parameters/SandboxName'
post:
operationId: stopSandbox
tags: [Compute]
summary: Stop a sandbox.
responses:
'200':
description: The stopped sandbox.
/sandboxes/{sandbox_name}/previews:
parameters:
- $ref: '#/components/parameters/SandboxName'
get:
operationId: listSandboxPreviews
tags: [Compute]
summary: List previews for a sandbox.
responses:
'200':
description: A list of sandbox previews.
post:
operationId: createSandboxPreview
tags: [Compute]
summary: Create a preview for a sandbox.
responses:
'200':
description: The created sandbox preview.
/sandboxes/{sandbox_name}/previews/{preview_name}/tokens:
parameters:
- $ref: '#/components/parameters/SandboxName'
- name: preview_name
in: path
required: true
schema:
type: string
get:
operationId: listSandboxPreviewTokens
tags: [Compute]
summary: List tokens for a sandbox preview.
responses:
'200':
description: A list of preview tokens.
post:
operationId: createSandboxPreviewToken
tags: [Compute]
summary: Create a token for a sandbox preview.
responses:
'200':
description: The created preview token.
/jobs:
get:
operationId: listJobs
tags: [Jobs]
summary: List all jobs in the workspace.
responses:
'200':
description: A list of jobs.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Job'
post:
operationId: createJob
tags: [Jobs]
summary: Create a new job.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'200':
description: The created job.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
/jobs/{job_id}:
parameters:
- name: job_id
in: path
required: true
schema:
type: string
get:
operationId: getJob
tags: [Jobs]
summary: Get a job by id.
responses:
'200':
description: The requested job.
put:
operationId: updateJob
tags: [Jobs]
summary: Update a job by id.
responses:
'200':
description: The updated job.
delete:
operationId: deleteJob
tags: [Jobs]
summary: Delete a job by id.
responses:
'200':
description: The deleted job.
/jobs/{job_id}/executions:
parameters:
- name: job_id
in: path
required: true
schema:
type: string
get:
operationId: listJobExecutions
tags: [Jobs]
summary: List executions for a job.
responses:
'200':
description: A list of job executions.
post:
operationId: createJobExecution
tags: [Jobs]
summary: Create (run) a job execution.
responses:
'200':
description: The created job execution.
/jobs/{job_id}/executions/{execution_id}:
parameters:
- name: job_id
in: path
required: true
schema:
type: string
- name: execution_id
in: path
required: true
schema:
type: string
get:
operationId: getJobExecution
tags: [Jobs]
summary: Get a job execution.
responses:
'200':
description: The requested job execution.
delete:
operationId: deleteJobExecution
tags: [Jobs]
summary: Delete a job execution.
responses:
'200':
description: The deleted job execution.
/policies:
get:
operationId: listPolicies
tags: [Policies]
summary: List all policies in the workspace.
responses:
'200':
description: A list of policies.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Policy'
post:
operationId: createPolicy
tags: [Policies]
summary: Create a new policy.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
responses:
'200':
description: The created policy.
content:
application/json:
schema:
$ref: '#/components/schemas/Policy'
/policies/{policy_name}:
parameters:
- name: policy_name
in: path
required: true
schema:
type: string
get:
operationId: getPolicy
tags: [Policies]
summary: Get a policy by name.
responses:
'200':
description: The requested policy.
put:
operationId: updatePolicy
tags: [Policies]
summary: Update a policy by name.
responses:
'200':
description: The updated policy.
delete:
operationId: deletePolicy
tags: [Policies]
summary: Delete a policy by name.
responses:
'200':
description: The deleted policy.
/integrations/{integration_name}:
parameters:
- name: integration_name
in: path
required: true
schema:
type: string
get:
operationId: getIntegration
tags: [Integrations]
summary: Get an integration by name.
responses:
'200':
description: The requested integration.
/integrations/connections:
get:
operationId: listIntegrationConnections
tags: [Integrations]
summary: List all integration connections in the workspace.
responses:
'200':
description: A list of integration connections.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IntegrationConnection'
post:
operationId: createIntegrationConnection
tags: [Integrations]
summary: Create a new integration connection.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationConnection'
responses:
'200':
description: The created integration connection.
/integrations/connections/{connection_name}:
parameters:
- $ref: '#/components/parameters/ConnectionName'
get:
operationId: getIntegrationConnection
tags: [Integrations]
summary: Get an integration connection by name.
responses:
'200':
description: The requested integration connection.
put:
operationId: updateIntegrationConnection
tags: [Integrations]
summary: Update an integration connection by name.
responses:
'200':
description: The updated integration connection.
delete:
operationId: deleteIntegrationConnection
tags: [Integrations]
summary: Delete an integration connection by name.
responses:
'200':
description: The deleted integration connection.
/integrations/connections/{connection_name}/models:
parameters:
- $ref: '#/components/parameters/ConnectionName'
get:
operationId: listIntegrationConnectionModels
tags: [Integrations]
summary: List models available through an integration connection.
responses:
'200':
description: A list of connection models.
/integrations/connections/{connection_name}/endpointConfigurations:
parameters:
- $ref: '#/components/parameters/ConnectionName'
get:
operationId: getIntegrationConnectionModelEndpointConfigurations
tags: [Integrations]
summary: Get endpoint configurations for an integration connection.
responses:
'200':
description: The endpoint configurations.
/workspaces:
get:
operationId: listWorkspaces
tags: [Workspaces]
summary: List all workspaces the caller belongs to.
responses:
'200':
description: A list of workspaces.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Workspace'
post:
operationId: createWorkspace
tags: [Workspaces]
summary: Create a new workspace.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Workspace'
responses:
'200':
description: The created workspace.
/workspaces/{workspace_name}:
parameters:
- name: workspace_name
in: path
required: true
schema:
type: string
get:
operationId: getWorkspace
tags: [Workspaces]
summary: Get a workspace by name.
responses:
'200':
description: The requested workspace.
put:
operationId: updateWorkspace
tags: [Workspaces]
summary: Update a workspace by name.
responses:
'200':
description: The updated workspace.
delete:
operationId: deleteWorkspace
tags: [Workspaces]
summary: Delete a workspace by name.
responses:
'200':
description: The deleted workspace.
/users:
get:
operationId: listWorkspaceUsers
tags: [Workspaces]
summary: List users in the current workspace.
responses:
'200':
description: A list of workspace users.
post:
operationId: inviteWorkspaceUser
tags: [Workspaces]
summary: Invite a user to the current workspace.
responses:
'200':
description: The invited user.
/service_accounts:
get:
operationId: getWorkspaceServiceAccounts
tags: [Service Accounts]
summary: List service accounts in the workspace.
responses:
'200':
description: A list of service accounts.
post:
operationId: createWorkspaceServiceAccount
tags: [Service Accounts]
summary: Create a workspace service account.
responses:
'200':
description: The created service account.
/service_accounts/{client_id}/api_keys:
parameters:
- name: client_id
in: path
required: true
schema:
type: string
get:
operationId: listApiKeysForServiceAccount
tags: [Service Accounts]
summary: List API keys for a service account.
responses:
'200':
description: A list of API keys.
post:
operationId: createApiKeyForServiceAccount
tags: [Service Accounts]
summary: Create an API key for a service account.
responses:
'200':
description: The created API key.
/volumes:
get:
operationId: listVolumes
tags: [Volumes]
summary: List all volumes in the workspace.
responses:
'200':
description: A list of volumes.
post:
operationId: createVolume
tags: [Volumes]
summary: Create a new volume.
responses:
'200':
description: The created volume.
/locations:
get:
operationId: listLocations
tags: [Locations]
summary: List available deployment locations.
responses:
'200':
description: A list of locations.
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-Blaxel-Authorization
description: API key supplied as "Bearer YOUR-API-KEY".
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: OAuth 2.0 short-lived JWT access token.
parameters:
AgentName:
name: agent_name
in: path
required: true
schema:
type: string
FunctionName:
name: function_name
in: path
required: true
schema:
type: string
ModelName:
name: model_name
in: path
required: true
schema:
type: string
SandboxName:
name: sandbox_name
in: path
required: true
schema:
type: string
ConnectionName:
name: connection_name
in: path
required: true
schema:
type: string
schemas:
Metadata:
type: object
properties:
name:
type: string
displayName:
type: string
workspace:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
labels:
type: object
additionalProperties:
type: string
Agent:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
description:
type: string
runtime:
type: object
policies:
type: array
items:
type: string
Function:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
description:
type: string
runtime:
type: object
integrationConnections:
type: array
items:
type: string
Model:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
runtime:
type: object
integrationConnections:
type: array
items:
type: string
Sandbox:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
runtime:
type: object
ttl:
type: string
memory:
type: integer
Job:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
runtime:
type: object
maxConcurrentTasks:
type: integer
maxRetries:
type: integer
timeout:
type: integer
Policy:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
type:
type: string
locations:
type: array
items:
type: object
flavors:
type: array
items:
type: object
IntegrationConnection:
type: object
properties:
metadata:
$ref: '#/components/schemas/Metadata'
spec:
type: object
properties:
integration:
type: string
config:
type: object
secret:
type: object
Workspace:
type: object
properties:
name:
type: string
displayName:
type: string
region:
type: string
createdAt:
type: string
format: date-time