openapi: 3.1.0
info:
title: Barbacane Control Plane API
description: |
REST API for managing API specifications, plugins, artifacts, and compilations
in the Barbacane API Gateway control plane.
version: 0.1.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: http://localhost:9090
description: Local development server
tags:
- name: Health
description: Health check endpoints
- name: Init
description: Project initialization
- name: Projects
description: Project management
- name: Specs
description: API specification management
- name: Plugins
description: Plugin registry management
- name: Artifacts
description: Compiled artifact management
- name: Compilations
description: Async compilation job management
- name: DataPlanes
description: Connected data plane management
- name: ApiKeys
description: API key management for data plane authentication
paths:
/health:
get:
tags: [Health]
summary: Health check
description: Returns the health status of the control plane and database connectivity.
operationId: healthCheck
responses:
'200':
description: Service is healthy
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'503':
description: Service unavailable (database connection failed)
/init:
post:
tags: [Init]
summary: Initialize project
description: |
Generate project files from a template. Returns the generated files
(barbacane.yaml, api.yaml, .gitignore) that can be downloaded.
operationId: initProject
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitRequest'
responses:
'200':
description: Project files generated
content:
application/json:
schema:
$ref: '#/components/schemas/InitResponse'
'400':
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs:
get:
tags: [Specs]
summary: List specs
description: List all registered API specifications with optional filtering.
operationId: listSpecs
parameters:
- name: type
in: query
description: Filter by spec type
schema:
type: string
enum: [openapi, asyncapi]
- name: name
in: query
description: Filter by name (case-insensitive partial match)
schema:
type: string
responses:
'200':
description: List of specs
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Spec'
post:
tags: [Specs]
summary: Upload spec
description: |
Upload a new API specification or create a new revision of an existing spec.
The spec name is extracted from the OpenAPI/AsyncAPI title field.
operationId: uploadSpec
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [file]
properties:
file:
type: string
format: binary
description: The OpenAPI or AsyncAPI specification file (YAML or JSON)
responses:
'201':
description: Spec uploaded successfully
content:
application/json:
schema:
$ref: '#/components/schemas/UploadResponse'
'400':
description: Invalid spec file
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs/{id}:
get:
tags: [Specs]
summary: Get spec
description: Get metadata for a specific spec by ID.
operationId: getSpec
parameters:
- $ref: '#/components/parameters/specId'
responses:
'200':
description: Spec metadata
content:
application/json:
schema:
$ref: '#/components/schemas/Spec'
'404':
description: Spec not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [Specs]
summary: Delete spec
description: Delete a spec and all its revisions.
operationId: deleteSpec
parameters:
- $ref: '#/components/parameters/specId'
responses:
'204':
description: Spec deleted
'404':
description: Spec not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs/{id}/history:
get:
tags: [Specs]
summary: Get spec history
description: Get the revision history for a spec.
operationId: getSpecHistory
parameters:
- $ref: '#/components/parameters/specId'
responses:
'200':
description: Revision history
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SpecRevision'
'404':
description: Spec not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs/{id}/content:
get:
tags: [Specs]
summary: Download spec content
description: Download the spec file content, optionally for a specific revision.
operationId: downloadSpecContent
parameters:
- $ref: '#/components/parameters/specId'
- name: revision
in: query
description: Specific revision number (defaults to latest)
schema:
type: integer
responses:
'200':
description: Spec file content
content:
application/yaml:
schema:
type: string
format: binary
'404':
description: Spec or revision not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs/{id}/compliance:
get:
tags: [Specs]
summary: Check spec compliance
description: |
Re-run compliance checks against the current plugin registry.
Returns warnings about unregistered plugins, type mismatches,
project enablement issues, and config schema violations.
operationId: getSpecCompliance
parameters:
- $ref: '#/components/parameters/specId'
responses:
'200':
description: Compliance warnings (empty array if fully compliant)
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ComplianceWarning'
'404':
description: Spec not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs/{id}/compile:
post:
tags: [Compilations]
summary: Start compilation
description: |
Start an asynchronous compilation job for this spec.
Returns immediately with a compilation ID that can be polled for status.
operationId: startCompilation
parameters:
- $ref: '#/components/parameters/specId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CompileRequest'
responses:
'202':
description: Compilation started
content:
application/json:
schema:
$ref: '#/components/schemas/Compilation'
'404':
description: Spec not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/specs/{id}/compilations:
get:
tags: [Compilations]
summary: List spec compilations
description: List all compilation jobs for a specific spec.
operationId: listSpecCompilations
parameters:
- $ref: '#/components/parameters/specId'
responses:
'200':
description: List of compilations
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Compilation'
'404':
description: Spec not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/compilations/{id}:
get:
tags: [Compilations]
summary: Get compilation status
description: Get the current status of a compilation job.
operationId: getCompilation
parameters:
- $ref: '#/components/parameters/compilationId'
responses:
'200':
description: Compilation status
content:
application/json:
schema:
$ref: '#/components/schemas/Compilation'
'404':
description: Compilation not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [Compilations]
summary: Delete compilation
description: Delete a compilation record.
operationId: deleteCompilation
parameters:
- $ref: '#/components/parameters/compilationId'
responses:
'204':
description: Compilation deleted
'404':
description: Compilation not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/plugins:
get:
tags: [Plugins]
summary: List plugins
description: List all registered plugins with optional filtering.
operationId: listPlugins
parameters:
- name: type
in: query
description: Filter by plugin type
schema:
type: string
enum: [middleware, dispatcher]
- name: name
in: query
description: Filter by plugin name
schema:
type: string
responses:
'200':
description: List of plugins
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Plugin'
post:
tags: [Plugins]
summary: Register plugin
description: Register a new plugin version in the registry.
operationId: registerPlugin
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [name, version, type, file]
properties:
name:
type: string
description: Plugin name
version:
type: string
description: Semantic version
type:
type: string
enum: [middleware, dispatcher]
description: Plugin type
description:
type: string
description: Human-readable description
capabilities:
type: string
description: JSON array of capability strings
config_schema:
type: string
description: JSON Schema for plugin configuration
file:
type: string
format: binary
description: WASM binary file
responses:
'201':
description: Plugin registered
content:
application/json:
schema:
$ref: '#/components/schemas/Plugin'
'400':
description: Invalid plugin data
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Plugin version already exists
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/plugins/{name}:
get:
tags: [Plugins]
summary: List plugin versions
description: List all versions of a specific plugin.
operationId: listPluginVersions
parameters:
- $ref: '#/components/parameters/pluginName'
responses:
'200':
description: List of plugin versions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Plugin'
'404':
description: Plugin not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/plugins/{name}/{version}:
get:
tags: [Plugins]
summary: Get plugin
description: Get metadata for a specific plugin version.
operationId: getPlugin
parameters:
- $ref: '#/components/parameters/pluginName'
- $ref: '#/components/parameters/pluginVersion'
responses:
'200':
description: Plugin metadata
content:
application/json:
schema:
$ref: '#/components/schemas/Plugin'
'404':
description: Plugin not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [Plugins]
summary: Delete plugin
description: Delete a specific plugin version.
operationId: deletePlugin
parameters:
- $ref: '#/components/parameters/pluginName'
- $ref: '#/components/parameters/pluginVersion'
responses:
'204':
description: Plugin deleted
'404':
description: Plugin not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: Plugin is referenced by an artifact
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/plugins/{name}/{version}/download:
get:
tags: [Plugins]
summary: Download plugin
description: Download the WASM binary for a plugin.
operationId: downloadPlugin
parameters:
- $ref: '#/components/parameters/pluginName'
- $ref: '#/components/parameters/pluginVersion'
responses:
'200':
description: Plugin WASM binary
content:
application/wasm:
schema:
type: string
format: binary
'404':
description: Plugin not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/artifacts:
get:
tags: [Artifacts]
summary: List artifacts
description: List all compiled artifacts.
operationId: listArtifacts
responses:
'200':
description: List of artifacts
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Artifact'
/artifacts/{id}:
get:
tags: [Artifacts]
summary: Get artifact
description: Get metadata for a specific artifact.
operationId: getArtifact
parameters:
- $ref: '#/components/parameters/artifactId'
responses:
'200':
description: Artifact metadata
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
'404':
description: Artifact not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [Artifacts]
summary: Delete artifact
description: Delete an artifact.
operationId: deleteArtifact
parameters:
- $ref: '#/components/parameters/artifactId'
responses:
'204':
description: Artifact deleted
'404':
description: Artifact not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/artifacts/{id}/download:
get:
tags: [Artifacts]
summary: Download artifact
description: Download the compiled .bca artifact file.
operationId: downloadArtifact
parameters:
- $ref: '#/components/parameters/artifactId'
responses:
'200':
description: Artifact .bca file
content:
application/octet-stream:
schema:
type: string
format: binary
'404':
description: Artifact not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects:
get:
tags: [Projects]
summary: List projects
description: List all projects.
operationId: listProjects
responses:
'200':
description: List of projects
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
post:
tags: [Projects]
summary: Create project
description: Create a new project.
operationId: createProject
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProjectRequest'
responses:
'201':
description: Project created
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects/{projectId}:
get:
tags: [Projects]
summary: Get project
description: Get a specific project by ID.
operationId: getProject
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: Project details
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'404':
description: Project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
put:
tags: [Projects]
summary: Update project
description: Update a project.
operationId: updateProject
parameters:
- $ref: '#/components/parameters/projectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProjectRequest'
responses:
'200':
description: Project updated
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'404':
description: Project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [Projects]
summary: Delete project
description: Delete a project and all its resources.
operationId: deleteProject
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'204':
description: Project deleted
'404':
description: Project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects/{projectId}/data-planes:
get:
tags: [DataPlanes]
summary: List connected data planes
description: List all data planes connected to this project.
operationId: listProjectDataPlanes
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: List of connected data planes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataPlane'
'404':
description: Project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects/{projectId}/data-planes/{dataPlaneId}:
get:
tags: [DataPlanes]
summary: Get data plane
description: Get details for a specific connected data plane.
operationId: getProjectDataPlane
parameters:
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/dataPlaneId'
responses:
'200':
description: Data plane details
content:
application/json:
schema:
$ref: '#/components/schemas/DataPlane'
'404':
description: Data plane or project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
delete:
tags: [DataPlanes]
summary: Disconnect data plane
description: Disconnect a data plane from the project. This closes the WebSocket connection.
operationId: disconnectProjectDataPlane
parameters:
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/dataPlaneId'
responses:
'204':
description: Data plane disconnected
'404':
description: Data plane or project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects/{projectId}/deploy:
post:
tags: [DataPlanes]
summary: Deploy to data planes
description: |
Notify all connected data planes that a new artifact is available.
Data planes will pull and load the artifact.
operationId: deployToProjectDataPlanes
parameters:
- $ref: '#/components/parameters/projectId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeployRequest'
responses:
'200':
description: Deployment initiated
content:
application/json:
schema:
$ref: '#/components/schemas/DeployResponse'
'404':
description: Project or artifact not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects/{projectId}/api-keys:
get:
tags: [ApiKeys]
summary: List API keys
description: List all API keys for a project. Only key prefixes are returned, not full keys.
operationId: listProjectApiKeys
parameters:
- $ref: '#/components/parameters/projectId'
responses:
'200':
description: List of API keys
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ApiKey'
'404':
description: Project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
post:
tags: [ApiKeys]
summary: Create API key
description: |
Create a new API key for data plane authentication.
The full key is only returned once in the response - store it securely.
operationId: createProjectApiKey
parameters:
- $ref: '#/components/parameters/projectId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateApiKeyRequest'
responses:
'201':
description: API key created (full key returned only once)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyCreated'
'400':
description: Invalid request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
'409':
description: API key name already exists
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/projects/{projectId}/api-keys/{keyId}:
delete:
tags: [ApiKeys]
summary: Revoke API key
description: Revoke an API key. Data planes using this key will be disconnected.
operationId: revokeProjectApiKey
parameters:
- $ref: '#/components/parameters/projectId'
- $ref: '#/components/parameters/apiKeyId'
responses:
'204':
description: API key revoked
'404':
description: API key or project not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
/ws/data-plane:
get:
tags: [DataPlanes]
summary: Data plane WebSocket connection
description: |
WebSocket endpoint for data plane connections. Data planes connect here
to register with the control plane, send heartbeats, and receive artifact
notifications.
**Protocol:**
1. Connect with WebSocket upgrade
2. Send `register` message with project_id and api_key
3. Receive `registered` confirmation with data_plane_id
4. Send periodic `heartbeat` messages (every 30 seconds)
5. Receive `artifact_available` when new deployments are triggered
**Messages (Data Plane → Control Plane):**
- `{"type": "register", "project_id": "uuid", "api_key": "bbk_...", "name": "optional-name"}`
- `{"type": "heartbeat", "artifact_id": "uuid"}`
**Messages (Control Plane → Data Plane):**
- `{"type": "registered", "data_plane_id": "uuid", "heartbeat_interval_secs": 30}`
- `{"type": "artifact_available", "artifact_id": "uuid", "download_url": "/artifacts/{id}/download", "sha256": "..."}`
- `{"type": "heartbeat_ack"}`
operationId: dataPlaneWebSocket
responses:
'101':
description: WebSocket upgrade successful
'401':
description: Invalid or missing API key
components:
parameters:
specId:
name: id
in: path
required: true
description: Spec UUID
schema:
type: string
format: uuid
compilationId:
name: id
in: path
required: true
description: Compilation UUID
schema:
type: string
format: uuid
artifactId:
name: id
in: path
required: true
description: Artifact UUID
schema:
type: string
format: uuid
pluginName:
name: name
in: path
required: true
description: Plugin name
schema:
type: string
pluginVersion:
name: version
in: path
required: true
description: Plugin version
schema:
type: string
projectId:
name: projectId
in: path
required: true
description: Project UUID
schema:
type: string
format: uuid
dataPlaneId:
name: dataPlaneId
in: path
required: true
description: Data plane UUID
schema:
type: string
format: uuid
apiKeyId:
name: keyId
in: path
required: true
description: API key UUID
schema:
type: string
format: uuid
schemas:
HealthResponse:
type: object
required: [status, version]
properties:
status:
type: string
enum: [healthy]
version:
type: string
description: Control plane version
Spec:
type: object
required: [id, name, current_sha256, spec_type, spec_version, created_at, updated_at]
properties:
id:
type: string
format: uuid
name:
type: string
description: Unique spec name (from OpenAPI/AsyncAPI title)
current_sha256:
type: string
description: SHA256 hash of the current revision
spec_type:
type: string
enum: [openapi, asyncapi]
spec_version:
type: string
description: OpenAPI/AsyncAPI version string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
SpecRevision:
type: object
required: [revision, sha256, filename, created_at]
properties:
revision:
type: integer
description: Revision number (1-indexed)
sha256:
type: string
description: SHA256 hash of the content
filename:
type: string
description: Original filename
created_at:
type: string
format: date-time
UploadResponse:
type: object
required: [id, name, revision, sha256]
properties:
id:
type: string
format: uuid
name:
type: string
revision:
type: integer
sha256:
type: string
Plugin:
type: object
required: [name, version, plugin_type, capabilities, config_schema, sha256, registered_at]
properties:
name:
type: string
version:
type: string
plugin_type:
type: string
enum: [middleware, dispatcher]
description:
type: string
nullable: true
capabilities:
type: array
items:
type: string
config_schema:
type: object
description: JSON Schema for plugin configuration
sha256:
type: string
description: SHA256 hash of the WASM binary
registered_at:
type: string
format: date-time
Artifact:
type: object
required: [id, manifest, sha256, size_bytes, compiler_version, compiled_at]
properties:
id:
type: string
format: uuid
manifest:
type: object
description: Artifact manifest with routes, plugins, etc.
sha256:
type: string
description: SHA256 hash of the artifact
size_bytes:
type: integer
format: int64
compiler_version:
type: string
compiled_at:
type: string
format: date-time
CompileRequest:
type: object
properties:
production:
type: boolean
default: true
description: Enable production mode checks
additional_specs:
type: array
items:
type: string
format: uuid
description: Additional spec IDs to bundle
Compilation:
type: object
required: [id, spec_id, status, production, started_at]
properties:
id:
type: string
format: uuid
spec_id:
type: string
format: uuid
status:
type: string
enum: [pending, compiling, succeeded, failed]
production:
type: boolean
additional_specs:
type: array
items:
type: string
format: uuid
artifact_id:
type: string
format: uuid
nullable: true
description: Set when compilation succeeds
errors:
type: array
items:
$ref: '#/components/schemas/CompilationError'
warnings:
type: array
items:
$ref: '#/components/schemas/CompilationError'
started_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
nullable: true
CompilationError:
type: object
required: [code, message]
properties:
code:
type: string
description: Error code (e.g., E1000)
message:
type: string
ComplianceWarning:
type: object
required: [code, message]
properties:
code:
type: string
description: Warning code (W1001–W1004)
example: W1001
message:
type: string
description: Human-readable warning message
location:
type: string
description: Where in the spec the issue was found (e.g., "GET /users", "global middlewares")
ProblemDetails:
type: object
description: RFC 9457 Problem Details
required: [type, title, status]
properties:
type:
type: string
format: uri
description: Error type URI
title:
type: string
description: Short human-readable summary
status:
type: integer
description: HTTP status code
detail:
type: string
description: Detailed explanation
instance:
type: string
description: URI identifying the specific occurrence
errors:
type: array
items:
$ref: '#/components/schemas/ValidationIssue'
ValidationIssue:
type: object
required: [code, message]
properties:
code:
type: string
message:
type: string
location:
type: string
description: JSON pointer to the error location
InitRequest:
type: object
required: [name]
properties:
name:
type: string
description: Project/API name (used in spec title)
template:
type: string
enum: [basic, minimal]
default: basic
description: Template to use
description:
type: string
description: Optional API description
version:
type: string
default: "1.0.0"
description: API version
InitResponse:
type: object
required: [files, next_steps]
properties:
files:
type: array
items:
$ref: '#/components/schemas/ProjectFile'
description: Generated project files
next_steps:
type: array
items:
type: string
description: Instructions for the user
ProjectFile:
type: object
required: [path, content]
properties:
path:
type: string
description: File path relative to project root
content:
type: string
description: File content
Project:
type: object
required: [id, name, created_at, updated_at]
properties:
id:
type: string
format: uuid
name:
type: string
description: Project name
description:
type: string
nullable: true
description: Optional project description
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
CreateProjectRequest:
type: object
required: [name]
properties:
name:
type: string
description: Project name
description:
type: string
description: Optional project description
UpdateProjectRequest:
type: object
properties:
name:
type: string
description: Project name
description:
type: string
nullable: true
description: Project description
DataPlane:
type: object
required: [id, project_id, status, metadata, created_at]
properties:
id:
type: string
format: uuid
project_id:
type: string
format: uuid
name:
type: string
nullable: true
description: Optional friendly name
artifact_id:
type: string
format: uuid
nullable: true
description: Currently deployed artifact
status:
type: string
enum: [online, offline, deploying]
description: Connection status
last_seen:
type: string
format: date-time
nullable: true
description: Last heartbeat timestamp
connected_at:
type: string
format: date-time
nullable: true
description: When the data plane connected
metadata:
type: object
description: Additional metadata (version, hostname, etc.)
created_at:
type: string
format: date-time
ApiKey:
type: object
required: [id, project_id, name, key_prefix, scopes, created_at]
properties:
id:
type: string
format: uuid
project_id:
type: string
format: uuid
name:
type: string
description: Human-readable key name
key_prefix:
type: string
description: Key prefix for identification (e.g., "bbk_abc1...")
scopes:
type: array
items:
type: string
description: Granted scopes
expires_at:
type: string
format: date-time
nullable: true
last_used_at:
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
revoked_at:
type: string
format: date-time
nullable: true
ApiKeyCreated:
type: object
required: [id, name, key, key_prefix, scopes, created_at]
description: Response when creating an API key. The full key is only returned once.
properties:
id:
type: string
format: uuid
name:
type: string
key:
type: string
description: The full API key (only returned once, store securely)
key_prefix:
type: string
description: Key prefix for future identification
scopes:
type: array
items:
type: string
expires_at:
type: string
format: date-time
nullable: true
created_at:
type: string
format: date-time
CreateApiKeyRequest:
type: object
required: [name]
properties:
name:
type: string
description: Human-readable key name
scopes:
type: array
items:
type: string
description: Scopes to grant (defaults to data-plane:connect)
expires_at:
type: string
format: date-time
description: Optional expiration time
DeployRequest:
type: object
properties:
artifact_id:
type: string
format: uuid
description: Specific artifact to deploy (defaults to latest)
DeployResponse:
type: object
required: [artifact_id, data_planes_notified]
properties:
artifact_id:
type: string
format: uuid
description: The artifact being deployed
data_planes_notified:
type: integer
description: Number of connected data planes notified