API Overview

Flyte exposes a single, unified API surface through FlyteAdmin. All control-plane operations — registering tasks and workflows, launching executions, querying status — go through this API.

AdminService

Full RPC reference for workflow, task, execution, and project management.

WorkflowSpec

WorkflowTemplate, Node, BranchNode, and compiled closure messages.

TaskSpec

TaskTemplate, Container, Resources, and RuntimeMetadata messages.

Execution

ExecutionSpec, phase enums, node/task execution messages.

Transport layer

Flyte’s API is defined in FlyteIDL using Protocol Buffers and served over two transports:

Transport	Endpoint	Use case
gRPC	`:81` (default)	High-performance programmatic access
REST (HTTP/1.1)	`:80` or `:443`	Browser clients, `curl`, third-party integrations

The REST gateway is generated automatically by grpc-gateway. Every gRPC method maps to an HTTP endpoint under /api/v1/. Response codes follow gRPC status → HTTP status mapping.

// From flyteidl/service/admin.proto
service AdminService {
  rpc CreateExecution (ExecutionCreateRequest)
      returns (ExecutionCreateResponse) {
    option (google.api.http) = {
      post: "/api/v1/executions"
      body: "*"
    };
  }
  // ... all methods have equivalent REST bindings
}

FlyteIDL — the schema layer

FlyteIDL (Interface Definition Language) is the single source of truth for every message and service in Flyte. All SDKs and components communicate through these protobuf types.

flyteidl/
├── service/
│   ├── admin.proto       # AdminService — primary API
│   ├── agent.proto       # Agent plugin service
│   └── auth.proto        # OAuth2 endpoints
└── core/
    ├── workflow.proto    # WorkflowTemplate, Node, BranchNode
    ├── tasks.proto       # TaskTemplate, Container, Resources
    ├── execution.proto   # Phase enums, ExecutionError
    ├── identifier.proto  # Identifier, WorkflowExecutionIdentifier
    └── literals.proto    # LiteralMap, Scalar, Primitive

Generated clients are available for:

Go: github.com/flyteorg/flyte/flyteidl/gen/pb-go/flyteidl
Python: flyteidl PyPI package
JavaScript: @flyteorg/flyteidl

Authentication

FlyteAdmin uses OAuth 2.0 with bearer tokens. Supported flows:

PKCE (recommended)
Client credentials
Bearer token (direct)

The default interactive flow for CLI and UI clients. Used by flytectl.

# ~/.flyte/config.yaml
admin:
  endpoint: dns:///flyte.example.com
  authType: Pkce
  insecure: false

For service accounts and automation. Pass a client_id and client_secret.

# ~/.flyte/config.yaml
admin:
  endpoint: dns:///flyte.example.com
  authType: ClientSecret
  clientId: my-service-account
  clientSecretLocation: /etc/flyte/secret

Supply the token directly in the Authorization header.

curl -H "Authorization: Bearer $TOKEN" \
  https://flyte.example.com/api/v1/projects

When insecure: true is set in the config, authentication is disabled. This is only appropriate for local development sandboxes.

Connecting to the API

Using flytectl

flytectl is the official CLI and wraps the gRPC API entirely:

# Install
curl -sL https://ctl.flyte.org/install | bash

# Configure endpoint
export FLYTECTL_CONFIG=~/.flyte/config.yaml

# List projects
flytectl get projects

Using grpcurl

grpcurl lets you call gRPC APIs from the command line:

# Install grpcurl
brew install grpcurl

# List all methods in AdminService
grpcurl -plaintext localhost:81 \
  describe flyteidl.service.AdminService

# List projects
grpcurl -plaintext localhost:81 \
  flyteidl.service.AdminService/ListProjects

Using the REST gateway

Every gRPC method is also available over HTTP. Use any HTTP client:

# List projects
curl http://localhost:30080/api/v1/projects

# Get a specific workflow
curl http://localhost:30080/api/v1/workflows/flytesnacks/development/my_workflow/v1

# Create an execution
curl -X POST http://localhost:30080/api/v1/executions \
  -H 'Content-Type: application/json' \
  -d '{
    "project": "flytesnacks",
    "domain": "development",
    "spec": {
      "launch_plan": {
        "project": "flytesnacks",
        "domain": "development",
        "name": "my_workflow",
        "version": "v1"
      }
    }
  }'

Python SDK (flytekit)

For programmatic use, FlyteRemote wraps the gRPC API:

from flytekit.remote import FlyteRemote
from flytekit.configuration import Config

remote = FlyteRemote(
    config=Config.for_endpoint("flyte.example.com"),
    default_project="flytesnacks",
    default_domain="development",
)

# Fetch a workflow
wf = remote.fetch_workflow(
    name="my_module.my_workflow",
    version="v1",
)

# Launch an execution
execution = remote.execute(wf, inputs={"name": "world"})
print(execution.id.name)  # e.g. "f5c17e1b5640c4336bf8"

Error codes

gRPC status codes map to HTTP status codes via the grpc-gateway standard:

gRPC Status	HTTP Status	Meaning
`OK`	`200`	Success
`INVALID_ARGUMENT`	`400`	Bad request / validation failure
`ALREADY_EXISTS`	`409`	Entity already registered at this version
`NOT_FOUND`	`404`	Requested entity does not exist
`UNAUTHENTICATED`	`401`	Missing or invalid credentials
`PERMISSION_DENIED`	`403`	Insufficient permissions
`INTERNAL`	`500`	Server-side error

When a 409 ALREADY_EXISTS is returned during registration, this is expected behavior — Flyte treats workflow and task versions as immutable. Re-registering the same version is a no-op that returns the conflict code.

gRPC / Protobuf API

API Overview

AdminService

WorkflowSpec

TaskSpec

Execution

Transport layer

FlyteIDL — the schema layer

Authentication

Connecting to the API

Using flytectl

Using grpcurl

Using the REST gateway

Python SDK (flytekit)

Error codes

Build docs developers (and LLMs) love

gRPC / Protobuf API

AdminService

WorkflowSpec

TaskSpec

Execution

​Transport layer

​FlyteIDL — the schema layer

​Authentication

​Connecting to the API

​Using flytectl

​Using grpcurl

​Using the REST gateway

​Python SDK (flytekit)

​Error codes

Build docs developers (and LLMs) love

Transport layer

FlyteIDL — the schema layer

Authentication

Connecting to the API

Using flytectl

Using grpcurl

Using the REST gateway

Python SDK (flytekit)

Error codes