Documentation menu

Getting started

New in v2.0

Feature deep dives

System atlas

Reference

Learn

REST API

Telegram Forwarding REST API Reference

All 102 routes the AutoTelegramForward control plane registers, grouped by subsystem, each with its verb, auth rule and a cURL example.

Verified against the checkout built for v2.2.4 · updated 20 Oct 2026

On this page

Where to go deeper
Authentication
Conventions
Worked examples
Group highlights
Complete route table
Delivery lifecycle
Errors & status codes

The control plane is a Go service that fronts the Python core. It owns authentication, tenancy, task CRUD, log history, dead-letter control and administration. Every route below is parsed out of api/main.go at build time, so this page cannot drift from the shipped binary.

102 endpoints68 require a token4 route groupsJSON in, JSON out

Where to go deeper

This page is the map. The four pages below are the territory: the full endpoint table with accepted fields, the response contract, the quota model and the durable-job lifecycle — each one grounded in the code that implements it rather than in a description of intent.

Endpoint reference

Every one of the 102 registered routes, searchable, with its accepted fields, its auth level and a real response body.

Response envelope

The three body shapes, the status codes that carry them, and the guard chain that decides whether a request ever reaches a handler.

Rate limits & quotas

Six classes with their real budgets, how each key is derived, and which classes refuse when the shared store is gone.

Durable task lifecycle

Six states with their full transition table, idempotent submission, retry backoff and every bound a caller can hit.

Tenant isolation

Owner scoping and the three refusals.

Secrets & keys

Encryption, write-only keys, rotation.

Request hardening

Caps, timeouts, the SSRF guard.

Authentication

Two schemes exist and they do different jobs. Clients (the web dashboard and the mobile app) obtain a session token from the public authentication routes and send it as a bearer token. Machines that call the API server-to-server can present a shared key instead.

Authentication schemes accepted by the control plane
Scheme	Header	Used by	Behaviour
`Bearer token`	`Authorization: Bearer <token>`	Web dashboard, mobile app, `atf auth token --save`	Resolves to an identity; every query is scoped to that numeric user id.
`ATF_API_KEY`	`X-API-Key: <key>`	Service-to-service automation	Only enforced when the key is configured on the server.
`Init data`	`POST /api/auth/tma`	Telegram Mini App	The signed WebApp init data is verified before a token is issued.

Bearer token
Header
Authorization: Bearer <token>
Used by
Web dashboard, mobile app, atf auth token --save
Behaviour
Resolves to an identity; every query is scoped to that numeric user id.
ATF_API_KEY
Header
X-API-Key: <key>
Used by
Service-to-service automation
Behaviour
Only enforced when the key is configured on the server.
Init data
Header
POST /api/auth/tma
Used by
Telegram Mini App
Behaviour
The signed WebApp init data is verified before a token is issued.

# 1. Exchange credentials for a token
TOKEN=$(curl -s -X POST https://your-host/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"…"}' \
  | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# 2. Read your own tasks
curl -s https://your-host/api/rules \
  -H "Authorization: Bearer $TOKEN"

# 3. Or use the CLI, which stores the token for you
atf auth token --save
atf auth whoami

Public readiness route (no token)

curl -s https://your-host/api/system/setup | jq

# {
#   "ready": true,
#   "version": "2.0.0",
#   "env": { "ATF_BOT_TOKEN": { "set": true } },
#   "services": { "core": true, "logger": true, "api": true, "web": true }
# }

# Ready verdict without probing the services:
curl -s 'https://your-host/api/system/setup?probe=0'

Conventions

Versioned aliases. Health and system routes answer on both /api/… and /api/v1/…; the dashboard uses the mirrored forms.
Partial updates are explicit. PATCH carries only what changes plus update_mask, which is the only way to set a field to false, zero or empty.
Optimistic concurrency. Updating a task bumps its version, so a stale writer is rejected instead of silently overwriting.
Correlation ids. Every response carries a correlation id that also appears in the log history, so an API call and its delivery can be joined.
Bounded reads. Log and queue queries page with limit / since rather than returning unbounded history.
Generated schema. The per-task settings surface publishes its own JSON schema at /api/rules/settings/schema, so editors can be built before any task exists.

Worked examples

Create a task with many sources and many targets

curl -s -X POST https://your-host/api/rules \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Market news → three channels",
    "source_chats": ["-1001111111111", "-1002222222222"],
    "target_chats": ["-1003333333333", "-1004444444444"],
    "settings": {
      "clean_links": true,
      "clean_mentions": true,
      "header_template": "📰 [[ORIGIN_NAME]]",
      "footer_template": "🔗 [[ORIGIN_LINK]]"
    }
  }'

Dry-run a rule before it goes live

curl -s -X POST https://your-host/api/simulate \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"rule_id":"<id>","text":"BUY NOW t.me/spam @channel #deal"}' | jq

Inspect history, then replay a dead-lettered job

curl -s "https://your-host/api/logs?level=ERROR&limit=50" \
  -H "Authorization: Bearer $TOKEN" | jq '.items[0]'

curl -s https://your-host/api/logs/stats -H "Authorization: Bearer $TOKEN" | jq

curl -s https://your-host/api/dlq -H "Authorization: Bearer $TOKEN" | jq '.items[].id'
curl -s -X POST https://your-host/api/dlq/<id>/retry \
  -H "Authorization: Bearer $TOKEN" | jq

Group highlights

System & readiness

GET /api/system/setupReady verdict, version, env contract and live service probes (booleans only)
GET /api/system/setup?probe=0The same verdict without probing the services
GET /api/system/envConfiguration contract: every key with set:true/false and a fix hint
GET /api/health/servicesPer-service reachability, latency and detail (core / logger / api / web)
GET /healthzLiveness probe used by the gateway and the upgrade gate

Tasks & rules

GET /api/rulesList the caller's tasks (tenant-scoped)
POST /api/rulesCreate a task with a source list, a target list and a content policy
GET /api/rules/{id}Read one task including its resolved settings
PUT /api/rules/{id}Update a task (optimistic concurrency, version bumped)
DELETE /api/rules/{id}Delete a task and its schedules
POST /api/rules/{id}/pausePause a task: queued jobs defer instead of failing
POST /api/rules/{id}/resumeResume a task and unblock retry-wait jobs
POST /api/rules/{id}/toggleEnable or disable a task
POST /api/simulateDry-run a message through a task and see the decision

Task lifecycle (async jobs)

GET /api/tasksList the caller's async jobs (state machine, tenant-scoped)
POST /api/tasksSubmit an async job (session backup, DLQ replay/purge, backup export); idempotent via idempotency_key
GET /api/tasks/{id}Poll one job: state, attempt, timestamps, structured error details
POST /api/tasks/{id}/cancelCancel a queued job before a worker claims it
POST /api/tasks/{id}/retryRe-queue a failed job (attempt budget reset)

Sessions

GET /api/sessionsList the caller's Telegram sessions
GET /api/sessions/{id}/chatsList the chats a session can see (sources and targets)
POST /api/sessions/{id}/backupExport an encrypted session backup
POST /api/backup/exportExport an encrypted backup of sessions and settings
POST /api/backup/importRestore from an encrypted backup
DELETE /api/sessions/{id}Terminate a session and purge its credentials

Filters & AI

GET /api/filtersList filter rules
POST /api/filtersCreate a filter rule
PUT /api/filters/{id}Update a filter rule
DELETE /api/filters/{id}Delete a filter rule
GET /api/ai-configsList AI rewrite configurations
POST /api/ai-configsCreate an AI configuration (provider, model, prompts)
PUT /api/ai-configs/{id}Update an AI configuration
POST /api/prompts/testSend sample text through a rewrite prompt

Observability

GET /api/logs?service=&level=&search=&limit=&since=Query attributable log history with bounded paging
GET /api/logs/statsAggregate counts by service and level
GET /api/logs/policyWhich levels and services the engine admits
POST /api/logs/purgePurge log history for one of the caller's own tasks (the installation-wide purge is administrator-only)
GET /api/statsDelivery throughput and outcome counters
GET /api/queueQueue depth and in-flight jobs
GET /api/dlqDead-lettered jobs
POST /api/dlq/{id}/retryReplay a dead-lettered job
DELETE /api/dlqPurge dead-lettered jobs for the caller scope (answers with the number removed)

Complete route table

All 102 registered routes, grouped by the mux that owns them and resolved through their mount prefixes. Host and scheme are yours; the paths are exact.

Service health & system · 12 routes

Endpoint	Handler	Auth
`GET /api/health/services`	`h.ServicesHealth`	Public
`GET /api/openapi.yaml`	`h.OpenAPIDoc`	Public
`GET /api/system/env`	`h.EnvContractHandler`	Public
`GET /api/system/setup`	`h.SetupReport`	Public
`GET /api/v1/health/services`	`h.ServicesHealth`	Public
`GET /api/v1/system/env`	`h.EnvContractHandler`	Public
`GET /api/v1/system/setup`	`h.SetupReport`	Public
`GET /api/version`	`h.Version`	Public
`GET /health`	`h.Health`	Public
`GET /healthz`	`h.Health`	Public
`GET /ready`	`h.Ready`	Public
`GET /readyz`	`h.Ready`	Public

GET /api/health/services
Handler
h.ServicesHealth
Auth
Public
GET /api/openapi.yaml
Handler
h.OpenAPIDoc
Auth
Public
GET /api/system/env
Handler
h.EnvContractHandler
Auth
Public
GET /api/system/setup
Handler
h.SetupReport
Auth
Public
GET /api/v1/health/services
Handler
h.ServicesHealth
Auth
Public
GET /api/v1/system/env
Handler
h.EnvContractHandler
Auth
Public
GET /api/v1/system/setup
Handler
h.SetupReport
Auth
Public
GET /api/version
Handler
h.Version
Auth
Public
GET /health
Handler
h.Health
Auth
Public
GET /healthz
Handler
h.Health
Auth
Public
GET /ready
Handler
h.Ready
Auth
Public
GET /readyz
Handler
h.Ready
Auth
Public

Authentication · 7 routes

Endpoint	Handler	Auth
`GET /api/auth/bot-login-link`	`h.AuthBotLoginLink`	Public
`PATCH /api/auth/change-password`	`h.AuthChangePassword`	Public
`POST /api/auth/exchange-bot-token`	`h.AuthBotExchange`	Public
`POST /api/auth/login`	`h.AuthLogin`	Public
`GET /api/auth/me`	`h.AuthMe`	Public
`POST /api/auth/register`	`h.AuthRegister`	Public
`POST /api/auth/tma`	`h.AuthTMA`	Public

Authenticated control plane · 71 routes

Endpoint	Handler	Auth
`GET /api/ai-configs`	`h.ListAIConfigs`	Bearer
`POST /api/ai-configs`	`h.CreateAIConfig`	Bearer
`PUT /api/ai-configs/{id}`	`h.UpdateAIConfig`	Bearer
`DELETE /api/ai-configs/{id}`	`h.DeleteAIConfig`	Bearer
`POST /api/ai-configs/check-key`	`h.CheckProviderKey`	Bearer
`GET /api/ai-configs/providers`	`h.ListAIProviders`	Bearer
`GET /api/audit/events`	`h.QueryAuditEvents`	Bearer
`POST /api/backup/export`	`h.BackupExport`	Bearer
`POST /api/backup/import`	`h.BackupImport`	Bearer
`GET /api/bot-tokens`	`h.ListBotTokens`	Bearer
`POST /api/bot-tokens`	`h.CreateBotToken`	Bearer
`DELETE /api/bot-tokens/{id}`	`h.DeleteBotToken`	Bearer
`GET /api/bot-tokens/{id}/defaults`	`h.GetBotDefaults`	Bearer
`PUT /api/bot-tokens/{id}/defaults`	`h.SetBotDefaults`	Bearer
`POST /api/client/credentials`	`h.ClientSaveCredentials`	Bearer
`GET /api/client/settings`	`h.ClientGetSettings`	Bearer
`GET /api/diagnostics`	`h.Diagnostics`	Bearer
`GET /api/dlq`	`h.ListDeadLetter`	Bearer
`DELETE /api/dlq`	`h.PurgeDeadLetter`	Bearer
`POST /api/dlq/{id}/retry`	`h.ReplayDeadLetter`	Bearer
`GET /api/filters`	`h.ListFilters`	Bearer
`POST /api/filters`	`h.CreateFilter`	Bearer
`PUT /api/filters/{id}`	`h.UpdateFilter`	Bearer
`DELETE /api/filters/{id}`	`h.DeleteFilter`	Bearer
`GET /api/logs`	`h.QueryLogs`	Bearer
`POST /api/logs/diagnostics/start`	`h.RequireAdmin(http.HandlerFunc(h.LogDiagnosticsStart))`	Public
`POST /api/logs/diagnostics/stop`	`h.RequireAdmin(http.HandlerFunc(h.LogDiagnosticsStop))`	Public
`GET /api/logs/export`	`h.ExportLogs`	Bearer
`GET /api/logs/health`	`h.LoggingHealth`	Bearer
`GET /api/logs/policy`	`h.LogPolicy`	Bearer
`PUT /api/logs/policy`	`h.RequireAdmin(http.HandlerFunc(h.LogPolicyUpdate))`	Public
`POST /api/logs/purge`	`h.PurgeLogs`	Bearer
`GET /api/logs/stats`	`h.LogStats`	Bearer
`GET /api/prompts`	`h.ListPromptTemplates`	Bearer
`POST /api/prompts`	`h.CreatePromptTemplate`	Bearer
`PUT /api/prompts/{id}`	`h.UpdatePromptTemplate`	Bearer
`DELETE /api/prompts/{id}`	`h.DeletePromptTemplate`	Bearer
`POST /api/prompts/test`	`h.TestPrompt`	Bearer
`GET /api/pv-responder`	`h.GetPVResponder`	Bearer
`POST /api/pv-responder`	`h.SetPVResponder`	Bearer
`PUT /api/pv-responder`	`h.SetPVResponder`	Bearer
`GET /api/queue`	`h.DeliveryStats`	Bearer
`GET /api/rules`	`h.ListRules`	Bearer
`POST /api/rules`	`h.CreateRule`	Bearer
`GET /api/rules/{id}`	`h.GetRule`	Bearer
`PUT /api/rules/{id}`	`h.UpdateRule`	Bearer
`PATCH /api/rules/{id}`	`h.UpdateRule`	Bearer
`DELETE /api/rules/{id}`	`h.DeleteRule`	Bearer
`POST /api/rules/{id}/duplicate`	`h.DuplicateRule`	Bearer
`GET /api/rules/{id}/logs`	`h.RuleLogs`	Bearer
`POST /api/rules/{id}/pause`	`h.PauseRule`	Bearer
`POST /api/rules/{id}/restart`	`h.RestartRule`	Bearer
`POST /api/rules/{id}/resume`	`h.ResumeRule`	Bearer
`POST /api/rules/{id}/route-path`	`h.RoutePathQuickSet`	Bearer
`GET /api/rules/{id}/settings`	`h.GetRuleSettings`	Bearer
`PUT /api/rules/{id}/settings`	`h.UpdateRuleSettings`	Bearer
`PATCH /api/rules/{id}/settings`	`h.UpdateRuleSettings`	Bearer
`POST /api/rules/{id}/stop`	`h.StopRule`	Bearer
`POST /api/rules/{id}/toggle`	`h.ToggleRule`	Bearer
`GET /api/rules/settings/schema`	`h.GetRuleSettingsSchema`	Bearer
`GET /api/sessions`	`h.ListSessions`	Bearer
`DELETE /api/sessions/{id}`	`h.TerminateSession`	Bearer
`POST /api/sessions/{id}/backup`	`h.BackupSession`	Bearer
`GET /api/sessions/{sessionId}/chats`	`h.ListChats`	Bearer
`POST /api/simulate`	`h.TestRule`	Bearer
`GET /api/stats`	`h.GetStats`	Bearer
`GET /api/tasks`	`h.ListTasks`	Bearer
`POST /api/tasks`	`h.CreateTask`	Bearer
`GET /api/tasks/{id}`	`h.GetTask`	Bearer
`POST /api/tasks/{id}/cancel`	`h.CancelTask`	Bearer
`POST /api/tasks/{id}/retry`	`h.RetryTask`	Bearer

GET /api/ai-configs
Handler
h.ListAIConfigs
Auth
Bearer
POST /api/ai-configs
Handler
h.CreateAIConfig
Auth
Bearer
PUT /api/ai-configs/{id}
Handler
h.UpdateAIConfig
Auth
Bearer
DELETE /api/ai-configs/{id}
Handler
h.DeleteAIConfig
Auth
Bearer
POST /api/ai-configs/check-key
Handler
h.CheckProviderKey
Auth
Bearer
GET /api/ai-configs/providers
Handler
h.ListAIProviders
Auth
Bearer
GET /api/audit/events
Handler
h.QueryAuditEvents
Auth
Bearer
POST /api/backup/export
Handler
h.BackupExport
Auth
Bearer
POST /api/backup/import
Handler
h.BackupImport
Auth
Bearer
GET /api/bot-tokens
Handler
h.ListBotTokens
Auth
Bearer
POST /api/bot-tokens
Handler
h.CreateBotToken
Auth
Bearer
DELETE /api/bot-tokens/{id}
Handler
h.DeleteBotToken
Auth
Bearer
GET /api/bot-tokens/{id}/defaults
Handler
h.GetBotDefaults
Auth
Bearer
PUT /api/bot-tokens/{id}/defaults
Handler
h.SetBotDefaults
Auth
Bearer
POST /api/client/credentials
Handler
h.ClientSaveCredentials
Auth
Bearer
GET /api/client/settings
Handler
h.ClientGetSettings
Auth
Bearer
GET /api/diagnostics
Handler
h.Diagnostics
Auth
Bearer
GET /api/dlq
Handler
h.ListDeadLetter
Auth
Bearer
DELETE /api/dlq
Handler
h.PurgeDeadLetter
Auth
Bearer
POST /api/dlq/{id}/retry
Handler
h.ReplayDeadLetter
Auth
Bearer
GET /api/filters
Handler
h.ListFilters
Auth
Bearer
POST /api/filters
Handler
h.CreateFilter
Auth
Bearer
PUT /api/filters/{id}
Handler
h.UpdateFilter
Auth
Bearer
DELETE /api/filters/{id}
Handler
h.DeleteFilter
Auth
Bearer
GET /api/logs
Handler
h.QueryLogs
Auth
Bearer
POST /api/logs/diagnostics/start
Handler
h.RequireAdmin(http.HandlerFunc(h.LogDiagnosticsStart))
Auth
Public
POST /api/logs/diagnostics/stop
Handler
h.RequireAdmin(http.HandlerFunc(h.LogDiagnosticsStop))
Auth
Public
GET /api/logs/export
Handler
h.ExportLogs
Auth
Bearer
GET /api/logs/health
Handler
h.LoggingHealth
Auth
Bearer
GET /api/logs/policy
Handler
h.LogPolicy
Auth
Bearer
PUT /api/logs/policy
Handler
h.RequireAdmin(http.HandlerFunc(h.LogPolicyUpdate))
Auth
Public
POST /api/logs/purge
Handler
h.PurgeLogs
Auth
Bearer
GET /api/logs/stats
Handler
h.LogStats
Auth
Bearer
GET /api/prompts
Handler
h.ListPromptTemplates
Auth
Bearer
POST /api/prompts
Handler
h.CreatePromptTemplate
Auth
Bearer
PUT /api/prompts/{id}
Handler
h.UpdatePromptTemplate
Auth
Bearer
DELETE /api/prompts/{id}
Handler
h.DeletePromptTemplate
Auth
Bearer
POST /api/prompts/test
Handler
h.TestPrompt
Auth
Bearer
GET /api/pv-responder
Handler
h.GetPVResponder
Auth
Bearer
POST /api/pv-responder
Handler
h.SetPVResponder
Auth
Bearer
PUT /api/pv-responder
Handler
h.SetPVResponder
Auth
Bearer
GET /api/queue
Handler
h.DeliveryStats
Auth
Bearer
GET /api/rules
Handler
h.ListRules
Auth
Bearer
POST /api/rules
Handler
h.CreateRule
Auth
Bearer
GET /api/rules/{id}
Handler
h.GetRule
Auth
Bearer
PUT /api/rules/{id}
Handler
h.UpdateRule
Auth
Bearer
PATCH /api/rules/{id}
Handler
h.UpdateRule
Auth
Bearer
DELETE /api/rules/{id}
Handler
h.DeleteRule
Auth
Bearer
POST /api/rules/{id}/duplicate
Handler
h.DuplicateRule
Auth
Bearer
GET /api/rules/{id}/logs
Handler
h.RuleLogs
Auth
Bearer
POST /api/rules/{id}/pause
Handler
h.PauseRule
Auth
Bearer
POST /api/rules/{id}/restart
Handler
h.RestartRule
Auth
Bearer
POST /api/rules/{id}/resume
Handler
h.ResumeRule
Auth
Bearer
POST /api/rules/{id}/route-path
Handler
h.RoutePathQuickSet
Auth
Bearer
GET /api/rules/{id}/settings
Handler
h.GetRuleSettings
Auth
Bearer
PUT /api/rules/{id}/settings
Handler
h.UpdateRuleSettings
Auth
Bearer
PATCH /api/rules/{id}/settings
Handler
h.UpdateRuleSettings
Auth
Bearer
POST /api/rules/{id}/stop
Handler
h.StopRule
Auth
Bearer
POST /api/rules/{id}/toggle
Handler
h.ToggleRule
Auth
Bearer
GET /api/rules/settings/schema
Handler
h.GetRuleSettingsSchema
Auth
Bearer
GET /api/sessions
Handler
h.ListSessions
Auth
Bearer
DELETE /api/sessions/{id}
Handler
h.TerminateSession
Auth
Bearer
POST /api/sessions/{id}/backup
Handler
h.BackupSession
Auth
Bearer
GET /api/sessions/{sessionId}/chats
Handler
h.ListChats
Auth
Bearer
POST /api/simulate
Handler
h.TestRule
Auth
Bearer
GET /api/stats
Handler
h.GetStats
Auth
Bearer
GET /api/tasks
Handler
h.ListTasks
Auth
Bearer
POST /api/tasks
Handler
h.CreateTask
Auth
Bearer
GET /api/tasks/{id}
Handler
h.GetTask
Auth
Bearer
POST /api/tasks/{id}/cancel
Handler
h.CancelTask
Auth
Bearer
POST /api/tasks/{id}/retry
Handler
h.RetryTask
Auth
Bearer

Administration · 12 routes

Endpoint	Handler	Auth
`GET /api/admin/admins`	`h.AdminListAdmins`	Public
`POST /api/admin/admins`	`h.AdminAddAdmin`	Public
`DELETE /api/admin/admins/{id}`	`h.AdminRemoveAdmin`	Public
`POST /api/admin/broadcast`	`h.AdminBroadcast`	Public
`GET /api/admin/extensions`	`h.AdminListExtensions`	Public
`POST /api/admin/extensions/{id}/toggle`	`h.AdminToggleExtension`	Public
`GET /api/admin/overview`	`h.AdminOverview`	Public
`GET /api/admin/ratelimit`	`h.RateLimitStatus`	Public
`GET /api/admin/settings`	`h.AdminGetSettings`	Public
`POST /api/admin/settings`	`h.AdminSaveSettings`	Public
`GET /api/admin/users`	`h.AdminListUsers`	Public
`POST /api/admin/users/{id}/status`	`h.AdminSetUserStatus`	Public

GET /api/admin/admins
Handler
h.AdminListAdmins
Auth
Public
POST /api/admin/admins
Handler
h.AdminAddAdmin
Auth
Public
DELETE /api/admin/admins/{id}
Handler
h.AdminRemoveAdmin
Auth
Public
POST /api/admin/broadcast
Handler
h.AdminBroadcast
Auth
Public
GET /api/admin/extensions
Handler
h.AdminListExtensions
Auth
Public
POST /api/admin/extensions/{id}/toggle
Handler
h.AdminToggleExtension
Auth
Public
GET /api/admin/overview
Handler
h.AdminOverview
Auth
Public
GET /api/admin/ratelimit
Handler
h.RateLimitStatus
Auth
Public
GET /api/admin/settings
Handler
h.AdminGetSettings
Auth
Public
POST /api/admin/settings
Handler
h.AdminSaveSettings
Auth
Public
GET /api/admin/users
Handler
h.AdminListUsers
Auth
Public
POST /api/admin/users/{id}/status
Handler
h.AdminSetUserStatus
Auth
Public

Delivery lifecycle

Every delivery moves through these states, and the same vocabulary is used by the queue API, the log history and the dashboard. Jobs in RETRY_WAIT are the ones a pause defers rather than fails.

RECEIVED
VALIDATING
AUTHORIZED
ACCEPTED
IN_PROGRESS
RETRY_WAIT
SUCCEEDED
FAILED
CANCELLED
OUTCOME_UNCONFIRMED

Errors & status codes

Status codes returned by the control plane
Code	When	What to do
`200`	Success.	Read the JSON body.
`400`	The body or query is malformed.	Check the settings schema and the environment contract.
`401`	Missing, expired or unverifiable token.	Log in again, or run `atf auth whoami`.
`403`	Administration route called without admin rights.	Use an administrator account.
`404`	The resource does not exist — or does not belong to you.	Ownership failures deliberately look identical to missing rows.
`409`	A concurrent update moved the version first.	Re-read the task, re-apply your change.
`422`	A setting was rejected by validation.	Read the field error in the response body.
`502`	The logger or core service is unreachable.	Check `/api/health/services` and `atf doctor`.

200
When
Success.
What to do
Read the JSON body.
400
When
The body or query is malformed.
What to do
Check the settings schema and the environment contract.
401
When
Missing, expired or unverifiable token.
What to do
Log in again, or run atf auth whoami.
403
When
Administration route called without admin rights.
What to do
Use an administrator account.
404
When
The resource does not exist — or does not belong to you.
What to do
Ownership failures deliberately look identical to missing rows.
409
When
A concurrent update moved the version first.
What to do
Re-read the task, re-apply your change.
422
When
A setting was rejected by validation.
What to do
Read the field error in the response body.
502
When
The logger or core service is unreachable.
What to do
Check /api/health/services and atf doctor.