Fleetctl API reference

OpenAPI specification

The public spec is https://fleetctl.ai/openapi.json. Every operation has a unique operationId, a description, typed parameters, and response schemas so function-calling clients can bind tools without scraping HTML.

curl -sS https://fleetctl.ai/openapi.json
curl -sS https://fleetctl.ai/api/health
curl -sS https://fleetctl.ai/api/catalog

JSON error responses

Unknown /api/* paths on fleetctl.ai return HTTP 404 with Content-Type: application/problem+json (RFC 9457). Agents must not parse the HTML 404 shell for API calls. Each problem includescode, detail, and resolution.

{
  "type": "https://fleetctl.ai/docs/api-reference/#errors",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "No Fleetctl public API operation matches this path.",
  "instance": "/api/does-not-exist",
  "resolution": "GET https://fleetctl.ai/openapi.json and pick an advertised operationId, or open https://fleetctl.ai/developers/."
}

Versioning and deprecation

The public discovery API on fleetctl.ai is v1. Explicit paths live under /api/v1/ (/api/v1/health, /api/v1/catalog, /api/v1/openapi.json). The shorter aliases /api/health and /api/catalog are the same v1 operations and will not change meaning.

Breaking changes ship as /api/v2. Before v1 is removed, responses will include a Sunset HTTP date and a Deprecation header at least 90 days in advance. This page is the deprecation policy; responses also advertise it with Link: rel="deprecation".

Unauthenticated discovery is limited to 120 requests per 60 seconds per client, advertised with IETF RateLimit-Policy and RateLimit headers. A 429 includes Retry-After.

Authentication

There are no long-lived raw API keys. Humans use the dashboard OAuth prompt or fleet login (device authorization). Workloads receive a client credential from fleet admin register after a self-serve trial at app.fleetctl.ai. Hosted MCP discovery: /.well-known/oauth-protected-resource. A token that tries to delegate a human sub through an actor claim is rejected.

Endpoints

Public discovery endpoints on fleetctl.ai. The same list is on /docs/api/ and /developers/.

• GET /openapi.json — OpenAPI 3.1 specification. Every operation has an operationId, typed parameters, and response schemas. Auth: none.
• GET /api/health — Public health JSON for Fleetctl discovery. Auth: none.
• GET /api/v1/health — Versioned alias of /api/health. Auth: none.
• GET /api/catalog — Developer catalog of public docs, OpenAPI, MCP, and CLI URLs. Auth: none.
• GET /.well-known/mcp.json — Ora MCP product manifest with the public hosted tool listing. Auth: none.
• GET /.well-known/api-catalog.json — RFC 9727 API catalog linking OpenAPI, docs, and OAuth metadata. Auth: none.
• GET /.well-known/oauth-protected-resource — OAuth protected-resource metadata for the hosted MCP. Auth: none.
• GET /mcp/tools.json — Static MCP tools/list catalog (same tools as POST /mcp tools/list). Auth: none.
• POST /mcp — Same-host Streamable HTTP MCP. Unauthenticated tools/call returns 401 with WWW-Authenticate. Auth: none for initialize, ping, and tools/list; OAuth Bearer for tools/call.
• POST /.well-known/mcp — Alternate same-host MCP handshake path, proxied to the hosted origin. Auth: none for initialize, ping, and tools/list; OAuth Bearer for tools/call.
• GET /llms.txt — Agent index: when to use Fleetctl, developer resources, and machine-readable URLs. Auth: none.
• GET /install — Official Fleetctl CLI installer script for the `fleet` binary. Auth: none.

Example requests

# Fleetctl developer resources — example requests

# OpenAPI spec
curl -sS https://fleetctl.ai/openapi.json

# Public health
curl -sS https://fleetctl.ai/api/health
# →
{
  "status": "ok",
  "product": "Fleetctl",
  "docs": "https://fleetctl.ai/docs/api-reference/",
  "openapi": "https://fleetctl.ai/openapi.json",
  "mcp": "https://app.fleetctl.ai/mcp"
}

# JSON error (unknown /api path)
curl -sS https://fleetctl.ai/api/does-not-exist
# → HTTP 404 application/problem+json
{
  "type": "https://fleetctl.ai/docs/api-reference/#errors",
  "title": "Not Found",
  "status": 404,
  "code": "not_found",
  "detail": "No Fleetctl public API operation matches this path.",
  "instance": "/api/does-not-exist",
  "resolution": "GET https://fleetctl.ai/openapi.json and pick an advertised operationId, or open https://fleetctl.ai/developers/."
}

# MCP initialize (public)
curl -sS -X POST https://fleetctl.ai/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

# MCP tools/list (public)
curl -sS -X POST https://fleetctl.ai/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# MCP tools/call without OAuth → 401 + WWW-Authenticate
curl -sS -D- -X POST https://fleetctl.ai/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"workflows.list","arguments":{}}}'

# Official CLI
curl -fsSL https://fleetctl.ai/install | sh
fleet version
fleet mcp serve

Workflow run states

Workflow API boundary

The browser uses authenticated definition, run, approval, artifact, and history routes. The local worker uses instance-token routes for pending runs, leases, trigger definitions, completion reports, and code results. These are deployment internals rather than a public unauthenticated REST API.

MCP transport

Hosted Streamable HTTP:
  Manifest: https://fleetctl.ai/.well-known/mcp.json
  Handshake: https://fleetctl.ai/.well-known/mcp
  Canonical resource: https://app.fleetctl.ai/mcp
  OAuth: https://fleetctl.ai/.well-known/oauth-protected-resource

Local stdio:
  fleet mcp serve
  Transport: JSON-RPC 2.0 over stdin/stdout
  Discovery: tools/list
  Invocation: tools/call

Server card:
  https://fleetctl.ai/.well-known/mcp/server-card.json

Prefer the hosted Streamable HTTP endpoint when the agent is not running on the customer's worker. Use stdio when the fleet binary is already installed. Discover tools rather than hard-coding a count; the registered surface evolves with the binary.

Agent environment

The removed pipeline-stage environment variables are not part of current workflow dispatch. Workflow instructions arrive through the assigned task and persisted run context.

Host controls

Data paths