Fleetctl Documentation

Authentication

Authentication for Fleetctl has two layers. Public discovery (/openapi.json, /api/health, /api/catalog, /mcp/tools.json, and MCP initialize/tools/list) needs no credential. Workflow, license, Lessons, and MCP tools/call require OAuth. There is no raw long-lived API key to paste.

1. Start free at https://app.fleetctl.ai — no credit card and no contact-sales form for Business.
2. Generate a registration code in the dashboard, then run fleet admin register. That issues the workload OAuth client. Humans use fleet login or the dashboard OAuth prompt.
3. Hosted MCP clients follow OAuth protected resource metadata. Scopes include fleet:access and Lessons scopes. Unauthenticated tools/call returns HTTP 401 with WWW-Authenticate: Bearer resource_metadata=....

Fleetctl does not publish customer-facing outbound webhooks. Inbound GitHub webhooks are configured per installation on the control plane. There is no public webhook signature catalog because there is no public outbound webhook API.

Endpoints

Predictable URLs. Unknown /api/* paths return RFC 9457 application/problem+json. HTML pages also speak markdown via Accept: text/markdown or by appending .md to the path.

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

Method Path                                      Auth
GET   /openapi.json                             none
GET   /api/health                               none
GET   /api/v1/health                            none
GET   /api/catalog                              none
GET   /.well-known/mcp.json                     none
GET   /.well-known/api-catalog.json             none
GET   /.well-known/oauth-protected-resource     none
GET   /mcp/tools.json                           none
POST  /mcp                                      none for initialize, ping, and tools/list; OAuth Bearer for tools/call
POST  /.well-known/mcp                          none for initialize, ping, and tools/list; OAuth Bearer for tools/call
GET   /llms.txt                                 none
GET   /install                                  none

Example requests

Copy-pasteable curls, JSON bodies, and the RFC 9457 error envelope.initialize and tools/list are public; tools/call without a Bearer token is HTTP 401.

# 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