Create, update, list, and get Projects and the Domains scoped within them - the top-level logical grouping for workflows, tasks, launch plans, and executions. gRPC (FlyteIDL AdminService) with an HTTP/JSON gateway under /api/v1/projects.
openapi: 3.0.1
info:
title: Union FlyteAdmin Control Plane API (HTTP/JSON Gateway)
description: >-
Conservative model of the documented HTTP/JSON gateway exposed by the
Union.ai / Flyte control plane (the FlyteIDL AdminService). The control
plane is primarily a gRPC service; an HTTP/JSON REST gateway is generated
automatically with grpc-gateway, mapping each gRPC method to an HTTP
endpoint under /api/v1/. Paths and methods below are taken from the public
FlyteIDL admin service google.api.http annotations. Request/response
bodies are modeled loosely (object) because the gRPC<->JSON mapping of the
full protobuf message tree is large and not maintained as a hand-authored
OpenAPI contract by the vendor.
termsOfService: https://www.union.ai/legal/terms-of-service
contact:
name: Union.ai
url: https://www.union.ai/contact
license:
name: Apache 2.0 (Flyte / FlyteIDL)
url: https://www.apache.org/licenses/LICENSE-2.0
version: '1.0'
servers:
- url: https://{org}.app.union.ai
description: Union BYOC / managed control plane (replace {org} with your tenant).
variables:
org:
default: your-org
- url: https://serverless.union.ai
description: Union Serverless control plane.
tags:
- name: Projects
- name: Domains
- name: Tasks
- name: Workflows
- name: Launch Plans
- name: Executions
- name: Node Executions
- name: Task Executions
- name: Version
paths:
/api/v1/projects:
get:
operationId: listProjects
tags: [Projects]
summary: List registered projects.
parameters:
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
- { $ref: '#/components/parameters/Filters' }
- { $ref: '#/components/parameters/SortBy' }
responses:
'200': { $ref: '#/components/responses/OK' }
post:
operationId: registerProject
tags: [Projects]
summary: Register a new project.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/projects/{id}:
get:
operationId: getProject
tags: [Projects]
summary: Get a single project by id.
parameters:
- name: id
in: path
required: true
schema: { type: string }
responses:
'200': { $ref: '#/components/responses/OK' }
put:
operationId: updateProject
tags: [Projects]
summary: Update an existing project.
parameters:
- name: id
in: path
required: true
schema: { type: string }
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/domains:
get:
operationId: listDomains
tags: [Domains]
summary: List the domains (e.g. development, staging, production).
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/tasks:
post:
operationId: createTask
tags: [Tasks]
summary: Register a versioned task.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/task_ids/{project}/{domain}:
get:
operationId: listTaskIds
tags: [Tasks]
summary: List task names (identifiers) in a project/domain.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/tasks/{project}/{domain}/{name}:
get:
operationId: listTasks
tags: [Tasks]
summary: List versions of a task.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/tasks/{project}/{domain}/{name}/{version}:
get:
operationId: getTask
tags: [Tasks]
summary: Get a single versioned task.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/PathVersion' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/workflows:
post:
operationId: createWorkflow
tags: [Workflows]
summary: Register a versioned workflow.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/workflow_ids/{project}/{domain}:
get:
operationId: listWorkflowIds
tags: [Workflows]
summary: List workflow names in a project/domain.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/workflows/{project}/{domain}/{name}:
get:
operationId: listWorkflows
tags: [Workflows]
summary: List versions of a workflow.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/workflows/{project}/{domain}/{name}/{version}:
get:
operationId: getWorkflow
tags: [Workflows]
summary: Get a single versioned workflow.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/PathVersion' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/launch_plans:
post:
operationId: createLaunchPlan
tags: [Launch Plans]
summary: Create a versioned launch plan.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/launch_plan_ids/{project}/{domain}:
get:
operationId: listLaunchPlanIds
tags: [Launch Plans]
summary: List launch plan names in a project/domain.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/launch_plans/{project}/{domain}/{name}:
get:
operationId: listLaunchPlans
tags: [Launch Plans]
summary: List versions of a launch plan.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/launch_plans/{project}/{domain}/{name}/{version}:
get:
operationId: getLaunchPlan
tags: [Launch Plans]
summary: Get a single versioned launch plan.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/PathVersion' }
responses:
'200': { $ref: '#/components/responses/OK' }
put:
operationId: updateLaunchPlan
tags: [Launch Plans]
summary: Update a launch plan's state (ACTIVE / INACTIVE) to schedule it.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/PathVersion' }
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/active_launch_plans/{project}/{domain}:
get:
operationId: listActiveLaunchPlans
tags: [Launch Plans]
summary: List the active (scheduled) launch plans in a project/domain.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/executions:
post:
operationId: createExecution
tags: [Executions]
summary: Launch a workflow execution from a launch plan.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/executions/relaunch:
post:
operationId: relaunchExecution
tags: [Executions]
summary: Relaunch a previously created execution.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/executions/recover:
post:
operationId: recoverExecution
tags: [Executions]
summary: Recover a failed execution from the last known successful point.
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/executions/{project}/{domain}:
get:
operationId: listExecutions
tags: [Executions]
summary: List executions in a project/domain.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
- { $ref: '#/components/parameters/Filters' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/executions/{project}/{domain}/{name}:
get:
operationId: getExecution
tags: [Executions]
summary: Get a single workflow execution.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
responses:
'200': { $ref: '#/components/responses/OK' }
put:
operationId: updateExecution
tags: [Executions]
summary: Update execution metadata (e.g. state).
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
requestBody: { $ref: '#/components/requestBodies/Generic' }
responses:
'200': { $ref: '#/components/responses/OK' }
delete:
operationId: terminateExecution
tags: [Executions]
summary: Terminate a running execution.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/data/executions/{project}/{domain}/{name}:
get:
operationId: getExecutionData
tags: [Executions]
summary: Get input/output data URLs for an execution.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/node_executions/{project}/{domain}/{name}:
get:
operationId: listNodeExecutions
tags: [Node Executions]
summary: List the node executions for a workflow execution.
parameters:
- { $ref: '#/components/parameters/PathProject' }
- { $ref: '#/components/parameters/PathDomain' }
- { $ref: '#/components/parameters/PathName' }
- { $ref: '#/components/parameters/Limit' }
- { $ref: '#/components/parameters/Token' }
responses:
'200': { $ref: '#/components/responses/OK' }
/api/v1/version:
get:
operationId: getVersion
tags: [Version]
summary: Get the FlyteAdmin control plane version.
responses:
'200': { $ref: '#/components/responses/OK' }
components:
parameters:
PathProject:
name: project
in: path
required: true
schema: { type: string }
PathDomain:
name: domain
in: path
required: true
schema: { type: string }
PathName:
name: name
in: path
required: true
schema: { type: string }
PathVersion:
name: version
in: path
required: true
schema: { type: string }
Limit:
name: limit
in: query
required: false
schema: { type: integer, format: int32 }
description: Maximum number of results to return for this page.
Token:
name: token
in: query
required: false
schema: { type: string }
description: Opaque pagination token returned by the previous page.
Filters:
name: filters
in: query
required: false
schema: { type: string }
description: FlyteAdmin filter expression (e.g. eq(execution.phase,RUNNING)).
SortBy:
name: sort_by.key
in: query
required: false
schema: { type: string }
description: Field key to sort the result set by.
requestBodies:
Generic:
required: true
content:
application/json:
schema:
type: object
description: >-
JSON projection of the corresponding FlyteIDL protobuf request
message. See the FlyteIDL admin protos for the exact field tree.
responses:
OK:
description: OK
content:
application/json:
schema:
type: object
description: >-
JSON projection of the corresponding FlyteIDL protobuf response
message.
securitySchemes:
OAuth2:
type: oauth2
description: >-
FlyteAdmin secures client connections with OAuth2. Interactive CLI/UI
clients use the Authorization Code + PKCE flow; machine clients use the
Client Credentials flow. User authentication to the console is via
OpenID Connect. Tokens are presented as a Bearer access token.
flows:
authorizationCode:
authorizationUrl: https://{org}.app.union.ai/oauth2/authorize
tokenUrl: https://{org}.app.union.ai/oauth2/token
scopes:
all: Full control-plane access.
clientCredentials:
tokenUrl: https://{org}.app.union.ai/oauth2/token
scopes:
all: Full control-plane access.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- OAuth2: [all]
- BearerAuth: []