REST API and Admin UI

arbiter-servant and arbiter-servant-ui provide the REST API and admin dashboard, as standalone WAI applications or as routes in an existing Servant API.

import Arbiter.Servant qualified as Servant
import Arbiter.Simple (createSimpleEnv, runSimpleDb)

env <- createSimpleEnv (Proxy @AppRegistry) connStr "arbiter"
config <- Servant.createArbiterServer (runSimpleDb env)
Servant.runArbiterAPI 8080 config

The server runs over any backend. Pass runHasqlDb env for a hasql application. The SSE stream uses the env's listener.

Embed as a sub-route in an existing Servant application:

import Arbiter.Servant qualified as Servant
import Arbiter.Servant.UI qualified as ServantUI

type MyAPI =
  "api" :> MyBusinessRoutes
    :<|> "arbiter" :> (Servant.ArbiterAPI AppRegistry :<|> ServantUI.AdminUI)

Server and route types: arbiter-servant Haddocks. UI route type: arbiter-servant-ui Haddocks.

POST jobs and POST jobs/batch enqueue from any language.

OpenAPI

arbiter-servant-openapi serves an OpenAPI 3 description of the API at /openapi.json:

import Arbiter.Servant (ArbiterAPI, arbiterServer, createArbiterServer)
import Arbiter.Servant.OpenApi (OpenApiAPI, openApiServer)
import Arbiter.Servant.UI (AdminUI, adminUIServer)

type MyApp = ArbiterAPI AppRegistry :<|> OpenApiAPI :<|> AdminUI

config <- createArbiterServer (runSimpleDb env)
run 8080 $
  serve (Proxy @MyApp) (arbiterServer config :<|> openApiServer @AppRegistry "1.0.0" :<|> adminUIServer)

[!NOTE] Mount OpenApiAPI before AdminUI. AdminUI is a Raw route that matches every path.

openApiSpec @AppRegistry "1.0.0" returns the same document as a Value. Module: arbiter-servant-openapi Haddocks.

Endpoints

Per-queue endpoints under /api/queues/:queue/:

Global endpoints under /api/:

Operating jobs

dlq/:id/retry and archive/:id/reenqueue take an optional replacement payload:

POST /api/queues/email_queue/dlq/12/retry
Content-Type: application/json

{"payload": {"tag": "SendWelcome", "contents": "alice@example.com"}}

jobs/:id/reschedule sets when a job becomes visible:

POST /api/queues/email_queue/jobs/41/reschedule
Content-Type: application/json

{"runAt": "2026-10-01T09:00:00Z"}

An in-flight, suspended, cancelled or exhausted job returns 409.

Consuming over HTTP

POST claim is the worker-pool claim: it spends admission tokens, increments the attempt count, records a claimant, and hides each job for the lease. A paused queue returns no leases.

POST /api/queues/email_queue/claim
{"maxJobs": 5, "leaseSeconds": 60}

maxJobs defaults to 1 and clamps to 1000. leaseSeconds defaults to 60 and clamps to 3600.

claimSeq and claimedBy in each returned job identify the lease. Every finalization request carries them:

POST /api/queues/email_queue/jobs/41/ack
{"claimSeq": 7, "claimedBy": "0f5e...c31"}

On a QueueWithResult queue, ack takes the result:

POST /api/queues/email_queue/jobs/41/ack
{"claimSeq": 7, "claimedBy": "0f5e...c31", "result": ["delivered"]}

The result is stored as ackWith stores it. A body that does not match the result type returns 400. Omit result to store none. The route needs FromJSON and ToJSON on the result type.

A mismatched lease, a lease that a registered worker holds, a suspended job, or a force-cancelled job returns 409.

The server does not renew an HTTP lease. After it expires another consumer can claim the job.

[!IMPORTANT] These routes have no authentication. Protect them with WAI middleware, a Servant authentication combinator, or an authenticating proxy.

Maintenance

POST maintenance runs one pass over stale workers, exhausted and cancelled jobs, rate-limit buckets, concurrency counts, archive and DLQ retention, and group summaries. Each operation runs in one caller at a time.

The response lists the affected row count per completed operation and the names of failed operations. Skipped operations appear in neither:

{"ops": {"sweep-stale-workers": 2, "purge-archives": 140}, "failed": []}

Worker pools run the same pass in their reaper. A pass covers every queue the migrations created in the schema, including queues outside the caller's registry. The endpoint supports deployments without worker pools.