openapi: 3.0.3
info:
title: ZenML OSS REST API
version: '1'
description: >-
REST API for the ZenML server, exposing operations to manage pipelines,
stacks, components, artifacts, models, deployments, runs, schedules,
secrets, users, projects, and triggers in a self-hosted ZenML deployment.
The API is consumed by the ZenML Python SDK and CLI and can also be
called directly for automation and CI/CD integration.
contact:
name: ZenML
url: https://docs.zenml.io/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://your-zenml-server.example.com/api/v1
description: ZenML server REST API (self-hosted)
security:
- bearerAuth: []
tags:
- name: Auth
description: Authentication and token management
- name: Pipelines
description: ML pipeline definitions
- name: Pipeline Runs
description: Pipeline run instances and their steps
- name: Stacks
description: ZenML stacks and their components
- name: Stack Components
description: Individual stack components such as orchestrators, artifact stores, and experiment trackers
- name: Artifacts
description: Artifact metadata and versions produced by pipeline runs
- name: Models
description: Registered models and their versions
- name: Deployments
description: Pipeline deployments
- name: Schedules
description: Scheduled pipeline runs
- name: Secrets
description: Encrypted secret storage
- name: Users
description: User accounts
- name: Projects
description: Project workspaces
- name: Service Connectors
description: Connectors to external infrastructure providers
paths:
/login:
post:
tags: [Auth]
summary: Login and Obtain Access Token
operationId: login
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required: [username, password]
properties:
username: { type: string }
password: { type: string, format: password }
responses:
'200':
description: Authentication succeeded
content:
application/json:
schema:
$ref: '#/components/schemas/TokenResponse'
'401':
description: Invalid credentials
/current-user:
get:
tags: [Users, Auth]
summary: Get Current Authenticated User
operationId: getCurrentUser
responses:
'200':
description: The current user
content:
application/json:
schema:
$ref: '#/components/schemas/User'
/pipelines:
get:
tags: [Pipelines]
summary: List Pipelines
operationId: listPipelines
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- in: query
name: name
schema: { type: string }
- in: query
name: project_id
schema: { type: string, format: uuid }
responses:
'200':
description: Page of pipelines
content:
application/json:
schema:
$ref: '#/components/schemas/PipelinePage'
post:
tags: [Pipelines]
summary: Create Pipeline
operationId: createPipeline
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRequest'
responses:
'201':
description: Pipeline created
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
/pipelines/{pipeline_id}:
parameters:
- $ref: '#/components/parameters/PipelineId'
get:
tags: [Pipelines]
summary: Get Pipeline
operationId: getPipeline
responses:
'200':
description: Pipeline detail
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline'
'404':
description: Pipeline not found
delete:
tags: [Pipelines]
summary: Delete Pipeline
operationId: deletePipeline
responses:
'204': { description: Pipeline deleted }
/runs:
get:
tags: [Pipeline Runs]
summary: List Pipeline Runs
operationId: listPipelineRuns
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- in: query
name: pipeline_id
schema: { type: string, format: uuid }
- in: query
name: status
schema: { $ref: '#/components/schemas/RunStatus' }
responses:
'200':
description: Page of pipeline runs
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRunPage'
/runs/{run_id}:
parameters:
- $ref: '#/components/parameters/RunId'
get:
tags: [Pipeline Runs]
summary: Get Pipeline Run
operationId: getPipelineRun
responses:
'200':
description: Pipeline run detail
content:
application/json:
schema:
$ref: '#/components/schemas/PipelineRun'
/stacks:
get:
tags: [Stacks]
summary: List Stacks
operationId: listStacks
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of stacks
content:
application/json:
schema:
$ref: '#/components/schemas/StackPage'
post:
tags: [Stacks]
summary: Create Stack
operationId: createStack
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StackRequest'
responses:
'201':
description: Stack created
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
/stacks/{stack_id}:
parameters:
- $ref: '#/components/parameters/StackId'
get:
tags: [Stacks]
summary: Get Stack
operationId: getStack
responses:
'200':
description: Stack detail
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
delete:
tags: [Stacks]
summary: Delete Stack
operationId: deleteStack
responses:
'204': { description: Stack deleted }
/components:
get:
tags: [Stack Components]
summary: List Stack Components
operationId: listStackComponents
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- in: query
name: type
schema: { type: string }
responses:
'200':
description: Page of stack components
content:
application/json:
schema:
$ref: '#/components/schemas/StackComponentPage'
/artifacts:
get:
tags: [Artifacts]
summary: List Artifacts
operationId: listArtifacts
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of artifacts
content:
application/json:
schema:
$ref: '#/components/schemas/ArtifactPage'
/artifacts/{artifact_id}:
parameters:
- in: path
name: artifact_id
required: true
schema: { type: string, format: uuid }
get:
tags: [Artifacts]
summary: Get Artifact
operationId: getArtifact
responses:
'200':
description: Artifact detail
content:
application/json:
schema:
$ref: '#/components/schemas/Artifact'
/models:
get:
tags: [Models]
summary: List Models
operationId: listModels
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of models
content:
application/json:
schema:
$ref: '#/components/schemas/ModelPage'
post:
tags: [Models]
summary: Create Model
operationId: createModel
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelRequest'
responses:
'201':
description: Model created
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
/model_versions:
get:
tags: [Models]
summary: List Model Versions
operationId: listModelVersions
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
- in: query
name: model_id
schema: { type: string, format: uuid }
responses:
'200':
description: Page of model versions
content:
application/json:
schema:
$ref: '#/components/schemas/ModelVersionPage'
/deployments:
get:
tags: [Deployments]
summary: List Pipeline Deployments
operationId: listDeployments
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of deployments
content:
application/json:
schema:
$ref: '#/components/schemas/DeploymentPage'
/schedules:
get:
tags: [Schedules]
summary: List Schedules
operationId: listSchedules
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of schedules
content:
application/json:
schema:
$ref: '#/components/schemas/SchedulePage'
/secrets:
get:
tags: [Secrets]
summary: List Secrets
operationId: listSecrets
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of secrets (without values)
content:
application/json:
schema:
$ref: '#/components/schemas/SecretPage'
post:
tags: [Secrets]
summary: Create Secret
operationId: createSecret
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SecretRequest'
responses:
'201':
description: Secret created
content:
application/json:
schema:
$ref: '#/components/schemas/Secret'
/users:
get:
tags: [Users]
summary: List Users
operationId: listUsers
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of users
content:
application/json:
schema:
$ref: '#/components/schemas/UserPage'
/projects:
get:
tags: [Projects]
summary: List Projects
operationId: listProjects
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of projects
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectPage'
/service_connectors:
get:
tags: [Service Connectors]
summary: List Service Connectors
operationId: listServiceConnectors
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/Size'
responses:
'200':
description: Page of service connectors
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceConnectorPage'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
Page:
in: query
name: page
schema: { type: integer, minimum: 1, default: 1 }
Size:
in: query
name: size
schema: { type: integer, minimum: 1, maximum: 1000, default: 20 }
PipelineId:
in: path
name: pipeline_id
required: true
schema: { type: string, format: uuid }
RunId:
in: path
name: run_id
required: true
schema: { type: string, format: uuid }
StackId:
in: path
name: stack_id
required: true
schema: { type: string, format: uuid }
schemas:
TokenResponse:
type: object
required: [access_token, token_type]
properties:
access_token: { type: string }
token_type: { type: string, example: bearer }
expires_in: { type: integer }
refresh_token: { type: string }
User:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
full_name: { type: string }
email: { type: string, format: email }
active: { type: boolean }
is_admin: { type: boolean }
created: { type: string, format: date-time }
updated: { type: string, format: date-time }
UserPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/User' }
Pipeline:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
description: { type: string }
version: { type: string }
spec:
type: object
additionalProperties: true
project_id: { type: string, format: uuid }
user_id: { type: string, format: uuid }
created: { type: string, format: date-time }
updated: { type: string, format: date-time }
PipelineRequest:
type: object
required: [name]
properties:
name: { type: string }
description: { type: string }
version: { type: string }
project_id: { type: string, format: uuid }
spec:
type: object
additionalProperties: true
PipelinePage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Pipeline' }
RunStatus:
type: string
enum:
- initializing
- running
- completed
- failed
- cached
- stopped
PipelineRun:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
pipeline_id: { type: string, format: uuid }
stack_id: { type: string, format: uuid }
status: { $ref: '#/components/schemas/RunStatus' }
start_time: { type: string, format: date-time }
end_time: { type: string, format: date-time }
user_id: { type: string, format: uuid }
created: { type: string, format: date-time }
PipelineRunPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/PipelineRun' }
Stack:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
description: { type: string }
components:
type: object
additionalProperties:
type: array
items: { type: string, format: uuid }
user_id: { type: string, format: uuid }
created: { type: string, format: date-time }
StackRequest:
type: object
required: [name]
properties:
name: { type: string }
description: { type: string }
components:
type: object
additionalProperties:
type: array
items: { type: string, format: uuid }
StackPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Stack' }
StackComponent:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
type:
type: string
enum:
- orchestrator
- artifact_store
- container_registry
- step_operator
- experiment_tracker
- model_deployer
- alerter
- annotator
- data_validator
- feature_store
- image_builder
- model_registry
flavor: { type: string }
configuration:
type: object
additionalProperties: true
created: { type: string, format: date-time }
StackComponentPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/StackComponent' }
Artifact:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
version: { type: string }
type: { type: string }
uri: { type: string, format: uri }
materializer: { type: string }
producer_step_run_id: { type: string, format: uuid }
created: { type: string, format: date-time }
ArtifactPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Artifact' }
Model:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
description: { type: string }
license: { type: string }
ethical_considerations: { type: string }
trade_offs: { type: string }
limitations: { type: string }
audience: { type: string }
use_cases: { type: string }
created: { type: string, format: date-time }
ModelRequest:
type: object
required: [name]
properties:
name: { type: string }
description: { type: string }
license: { type: string }
use_cases: { type: string }
ModelPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Model' }
ModelVersion:
type: object
properties:
id: { type: string, format: uuid }
model_id: { type: string, format: uuid }
name: { type: string }
number: { type: integer }
stage:
type: string
enum: [none, staging, production, archived]
description: { type: string }
created: { type: string, format: date-time }
ModelVersionPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/ModelVersion' }
Deployment:
type: object
properties:
id: { type: string, format: uuid }
pipeline_id: { type: string, format: uuid }
stack_id: { type: string, format: uuid }
status: { type: string }
created: { type: string, format: date-time }
DeploymentPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Deployment' }
Schedule:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
cron_expression: { type: string }
start_time: { type: string, format: date-time }
end_time: { type: string, format: date-time }
interval_seconds: { type: integer }
active: { type: boolean }
pipeline_id: { type: string, format: uuid }
created: { type: string, format: date-time }
SchedulePage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Schedule' }
Secret:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
scope: { type: string, enum: [user, workspace] }
values:
type: object
additionalProperties: { type: string }
created: { type: string, format: date-time }
SecretRequest:
type: object
required: [name, values]
properties:
name: { type: string }
scope: { type: string, enum: [user, workspace], default: workspace }
values:
type: object
additionalProperties: { type: string }
SecretPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Secret' }
Project:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
description: { type: string }
created: { type: string, format: date-time }
ProjectPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/Project' }
ServiceConnector:
type: object
properties:
id: { type: string, format: uuid }
name: { type: string }
connector_type: { type: string }
auth_method: { type: string }
resource_types:
type: array
items: { type: string }
configuration:
type: object
additionalProperties: true
created: { type: string, format: date-time }
ServiceConnectorPage:
allOf:
- $ref: '#/components/schemas/Page'
- type: object
properties:
items:
type: array
items: { $ref: '#/components/schemas/ServiceConnector' }
Page:
type: object
properties:
index: { type: integer }
max_size: { type: integer }
total_pages: { type: integer }
total: { type: integer }