AdminService

The AdminService is the primary gRPC service exposed by FlyteAdmin. It is defined in flyteidl/service/admin.proto and served over both gRPC and HTTP (via grpc-gateway at /api/v1/...).

syntax = "proto3";
package flyteidl.service;

// Served over gRPC and HTTP via grpc-gateway.
// Standard response codes: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/runtime/errors.go
service AdminService { ... }

Task management

CreateTask

Registers a new task definition. Task versions are immutable — re-registering the same (project, domain, name, version) tuple returns ALREADY_EXISTS.

POST /api/v1/tasks

Identifier

required

Globally unique task identifier. Contains project, domain, name, and version fields.

spec

TaskSpec

required

The task specification including the compiled closure with the task template.

Identifier

The identifier of the created task as stored in FlyteAdmin.

# grpcurl example
grpcurl -plaintext -d '{
  "id": {
    "project": "flytesnacks",
    "domain": "development",
    "name": "my_module.my_task",
    "version": "v1"
  },
  "spec": { ... }
}' localhost:81 flyteidl.service.AdminService/CreateTask

GetTask

Fetches a task definition by its full identifier.

GET /api/v1/tasks/{id.project}/{id.domain}/{id.name}/{id.version}

id.project

string

required

Project name.

id.domain

string

required

Domain name (e.g. development, staging, production).

id.name

string

required

Fully qualified task name.

id.version

string

required

Task version string.

ListTasks

Returns a paginated list of task definitions matching the given filters.

GET /api/v1/tasks/{id.project}/{id.domain}/{id.name}
GET /api/v1/tasks/{id.project}/{id.domain}

limit

uint32

Maximum number of items to return.

token

string

Pagination token from a prior response.

filters

string

Filter expression (e.g. eq(phase,SUCCEEDED)).

sort_by.key

string

Field to sort by.

ListTaskIds

Returns a list of unique task name identifiers for a project/domain — without version information.

GET /api/v1/task_ids/{project}/{domain}

Workflow management

CreateWorkflow

Registers a compiled workflow definition. Like tasks, workflow versions are immutable.

POST /api/v1/workflows

Identifier

required

Workflow identifier with project, domain, name, and version.

spec

WorkflowSpec

required

The workflow spec containing the compiled workflow closure.

Identifier

The stored workflow identifier.

GetWorkflow

GET /api/v1/workflows/{id.project}/{id.domain}/{id.name}/{id.version}

ListWorkflows

GET /api/v1/workflows/{id.project}/{id.domain}/{id.name}
GET /api/v1/workflows/{id.project}/{id.domain}

ListWorkflowIds

Returns unique workflow name identifiers for a project/domain without version information.

GET /api/v1/workflow_ids/{project}/{domain}

Launch plan management

Launch plans are versioned configurations that define how a workflow should be launched: which inputs to fix, any schedules, and notification settings.

CreateLaunchPlan

POST /api/v1/launch_plans

Identifier

required

Launch plan identifier.

spec

LaunchPlanSpec

required

Spec including the workflow identifier, fixed inputs, default inputs, and optional schedule.

GetLaunchPlan

GET /api/v1/launch_plans/{id.project}/{id.domain}/{id.name}/{id.version}

GetActiveLaunchPlan

At most one version of a launch plan can be ACTIVE at any time. This method fetches the currently active version.

GET /api/v1/active_launch_plans/{id.project}/{id.domain}/{id.name}

UpdateLaunchPlan

Activates or deactivates a launch plan version. Activating a version automatically deactivates the previously active version and updates any associated schedules.

PUT /api/v1/launch_plans/{id.project}/{id.domain}/{id.name}/{id.version}

Identifier

required

Launch plan identifier.

state

LaunchPlanState

required

INACTIVE (0) or ACTIVE (1).

ListActiveLaunchPlans

GET /api/v1/active_launch_plans/{project}/{domain}

Execution management

CreateExecution

Launches a new workflow execution from a launch plan.

POST /api/v1/executions

project

string

required

Target project for the execution.

domain

string

required

Target domain for the execution.

name

string

Optional execution name. If omitted, a unique name is auto-generated.

spec

ExecutionSpec

required

Execution specification including the launch plan reference and input values.

WorkflowExecutionIdentifier

The (project, domain, name) identifier for the created execution.

curl -X POST https://flyte.example.com/api/v1/executions \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "flytesnacks",
    "domain": "development",
    "spec": {
      "launch_plan": {
        "project": "flytesnacks",
        "domain": "development",
        "name": "my_module.my_workflow",
        "version": "v1"
      },
      "inputs": {
        "literals": {
          "name": { "scalar": { "primitive": { "string_value": "world" } } }
        }
      }
    }
  }'

GetExecution

Fetches a workflow execution by its identifier.

GET /api/v1/executions/{id.project}/{id.domain}/{id.name}

WorkflowExecutionIdentifier

Execution identifier.

spec

ExecutionSpec

The original execution spec.

closure

ExecutionClosure

Runtime state including phase, started_at, duration, and error (if failed).

ListExecutions

Returns a paginated list of workflow executions for a project/domain.

GET /api/v1/executions/{id.project}/{id.domain}

filters

string

Filter expression. Example: eq(phase,SUCCEEDED) or gte(started_at,2024-01-01T00:00:00Z).

limit

uint32

Page size. Default is 100.

token

string

Pagination token.

UpdateExecution

Updates mutable metadata on an execution (e.g. tags, state overrides).

PUT /api/v1/executions/{id.project}/{id.domain}/{id.name}

TerminateExecution

Aborts an in-progress execution. Running nodes are interrupted and resources are cleaned up.

DELETE /api/v1/executions/{id.project}/{id.domain}/{id.name}

WorkflowExecutionIdentifier

required

Execution to terminate.

cause

string

Human-readable reason for termination.

grpcurl -plaintext -d '{
  "id": {
    "project": "flytesnacks",
    "domain": "development",
    "name": "fe92c0a8cbf684ad"
  },
  "cause": "Cancelling stale run"
}' localhost:81 flyteidl.service.AdminService/TerminateExecution

RelaunchExecution

Creates a new execution identical to an existing one. All inputs and configuration are copied.

POST /api/v1/executions/relaunch

RecoverExecution

Recreates a previously-failed execution, resuming from the last known failure point. Inputs and version cannot be changed in recover mode.

POST /api/v1/executions/recover

RecoverExecution is useful after system failures (K8s cluster loss, platform bugs, retry exhaustion). Flyte replays completed nodes from cache and only re-executes failed nodes.

GetExecutionData

Fetches the raw input and output data for an execution.

GET /api/v1/data/executions/{id.project}/{id.domain}/{id.name}

GetExecutionMetrics

Returns runtime performance metrics for an execution.

GET /api/v1/metrics/executions/{id.project}/{id.domain}/{id.name}

Node and task execution

GetNodeExecution

Fetches a single node execution within a workflow execution.

GET /api/v1/node_executions/{id.execution_id.project}/{id.execution_id.domain}/{id.execution_id.name}/{id.node_id}

id.node_id

string

required

The node ID from the workflow graph (e.g. n0, n1, start-node).

ListNodeExecutions

GET /api/v1/node_executions/{workflow_execution_id.project}/{workflow_execution_id.domain}/{workflow_execution_id.name}

GetNodeExecutionData

Fetches input/output data for a specific node execution.

GET /api/v1/data/node_executions/{id.execution_id.project}/{id.execution_id.domain}/{id.execution_id.name}/{id.node_id}

GetTaskExecution

Fetches a single task execution attempt. Task executions are identified by node execution ID plus a retry attempt number.

GET /api/v1/task_executions/{id.node_execution_id.execution_id.project}/.../{id.retry_attempt}

ListTaskExecutions

GET /api/v1/task_executions/{node_execution_id.execution_id.project}/{node_execution_id.execution_id.domain}/{node_execution_id.execution_id.name}/{node_execution_id.node_id}

# Example: list task executions for node n0 in execution fe92c0a8cbf684ad19a8
curl 'http://localhost:30080/api/v1/task_executions/flytesnacks/development/fe92c0a8cbf684ad19a8/n0?limit=10'

GetTaskExecutionData

GET /api/v1/data/task_executions/...

Event recording

FlytePropeller reports phase transitions using these event endpoints. These are typically called by the execution engine, not external clients.

Method	HTTP	Description
`CreateWorkflowEvent`	`POST /api/v1/events/workflows`	Record a workflow phase transition
`CreateNodeEvent`	`POST /api/v1/events/nodes`	Record a node phase transition
`CreateTaskEvent`	`POST /api/v1/events/tasks`	Record a task phase transition

Project and domain management

RegisterProject

Registers a new project in the Flyte deployment.

POST /api/v1/projects

project.id

string

required

Unique project identifier (lowercase alphanumeric, hyphens allowed).

project.name

string

required

Human-readable project name.

project.description

string

Project description.

GetProject / ListProjects / UpdateProject

GET  /api/v1/projects/{id}
GET  /api/v1/projects
PUT  /api/v1/projects/{id}

GetDomains

Returns the list of registered domains. Domains are global across all projects.

GET /api/v1/domains

Matchable attributes

Matchable attributes allow overriding resource configuration at the project, project-domain, or workflow level:

Method	HTTP
`UpdateProjectDomainAttributes`	`PUT /api/v1/project_domain_attributes/{project}/{domain}`
`GetProjectDomainAttributes`	`GET /api/v1/project_domain_attributes/{project}/{domain}`
`DeleteProjectDomainAttributes`	`DELETE /api/v1/project_domain_attributes/{project}/{domain}`
`UpdateProjectAttributes`	`PUT /api/v1/project_attributes/{project}`
`UpdateWorkflowAttributes`	`PUT /api/v1/workflow_attributes/{project}/{domain}/{workflow}`
`ListMatchableAttributes`	`GET /api/v1/matchable_attributes`

Version

GetVersion

Returns the build information for the running FlyteAdmin instance.

GET /api/v1/version

curl http://localhost:30080/api/v1/version
# {"controlPlaneVersion":{"Version":"v1.16.4","Build":"...","BuildTime":"..."}}

gRPC / Protobuf API

​Task management

​CreateTask

​GetTask

​ListTasks

​ListTaskIds

​Workflow management

​CreateWorkflow

​GetWorkflow

​ListWorkflows

​ListWorkflowIds

​Launch plan management

​CreateLaunchPlan

​GetLaunchPlan

​GetActiveLaunchPlan

​UpdateLaunchPlan

​ListActiveLaunchPlans

​Execution management

​CreateExecution

​GetExecution

​ListExecutions

​UpdateExecution

​TerminateExecution

​RelaunchExecution

​RecoverExecution

​GetExecutionData

​GetExecutionMetrics

​Node and task execution

​GetNodeExecution

​ListNodeExecutions

​GetNodeExecutionData

​GetTaskExecution

​ListTaskExecutions

​GetTaskExecutionData

​Event recording

​Project and domain management

​RegisterProject

​GetProject / ListProjects / UpdateProject

​GetDomains

​Matchable attributes

​Version

​GetVersion

Build docs developers (and LLMs) love

Task management

CreateTask

GetTask

ListTasks

ListTaskIds

Workflow management

CreateWorkflow

GetWorkflow

ListWorkflows

ListWorkflowIds

Launch plan management

CreateLaunchPlan

GetLaunchPlan

GetActiveLaunchPlan

UpdateLaunchPlan

ListActiveLaunchPlans

Execution management

CreateExecution

GetExecution

ListExecutions

UpdateExecution

TerminateExecution

RelaunchExecution

RecoverExecution

GetExecutionData

GetExecutionMetrics

Node and task execution

GetNodeExecution

ListNodeExecutions

GetNodeExecutionData

GetTaskExecution

ListTaskExecutions

GetTaskExecutionData

Event recording

Project and domain management

RegisterProject

GetProject / ListProjects / UpdateProject

GetDomains

Matchable attributes

Version

GetVersion