HTTP API reference

Read this if you call laidline serve from your own code, a gateway or a load balancer. You will find every route with its method, authentication, request, response and error codes, and the shape of a detect result. Skip if you only use the library or the command line (Command line reference), or you point an OpenAI client at the proxy (OpenAI-compatible proxy). Time: 5 minutes to find a route. Needs: pip install "laidline[server]" and a running laidline serve.

In short

• laidline serve listens on 127.0.0.1:8080 unless you pass --host. Every example below uses that address.
• GET /healthz, /readyz, /metrics, POST /detect and GET /v1/assets/{name} never need a token. The mark and proxy routes need a bearer token once you set server.mark_token_env; /admin has its own bearer token.
• Request bodies over server.max_upload_bytes (64 MiB) get 413, video uploads excepted (they have jobs.max_upload_bytes). A missing or wrong token gets 401.
• POST /v1/mark/image and /v1/mark/audio answer with the marked file; the ids come back in X-Laidline-* headers. Video is asynchronous: 202, then poll GET /v1/jobs/{id}.
• POST /detect is free, returns a laidline.detect/1 result and is rate limited per address.

Before you call

Start the sidecar from a directory that holds your laidline.yaml (see Quickstart):

laidline serve

2026-10-26 08:55:52,623 INFO laidline.cli listening on 127.0.0.1:8080 (loopback only)
...
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

Check that it is ready:

curl -i localhost:8080/readyz

HTTP/1.1 200 OK
content-type: application/json

{"ready":true,"error":null}

The sidecar also serves the interactive pages FastAPI generates, /docs and /openapi.json. They list the routes below except /admin. With server.mark_token_env set they need the mark token.

Authentication

The mark token. Set server.mark_token_env to the name of an environment variable (not the token itself). While that variable holds at least 32 characters, every route in the table that needs it answers 401 without a matching Authorization: Bearer <token>. The server reads the variable on every request, so you can set or rotate the token without a restart. If the variable is unset or shorter than 32 characters, the routes stay open and the start-up log says so. A request that passes has its Authorization header removed, so the token never reaches an upstream. An upstream.auth: passthrough upstream then gets no key: use upstream.auth: env there (OpenAI-compatible proxy).

The admin token. /admin answers 404 as if the path did not exist unless the variable named by admin.token_env (default LAIDLINE_ADMIN_TOKEN) holds at least 32 characters. With it set, a missing or wrong token gets 401 with WWW-Authenticate: Bearer. The server reads the variable on every request.

Both tokens are compared in constant time and never appear in logs, errors or metrics.

Errors

Native routes return one of three bodies. A proxy route returns an OpenAI-shaped body.

Every 401 for the mark token carries WWW-Authenticate: Bearer.

Health and metrics

GET /healthz

Answers 200 with {"status": "ok"} as long as the process is up. It never touches the signer, so use it for liveness.

GET /readyz

Answers 200 with {"ready": true, "error": null} once the start-up self-test passed. The self-test marks a small image with the real signer, timestamp server and evidence sink, and is never counted against your credits. It answers 503 with {"ready": false, "error": "<category>"} while the self-test fails. /readyz re-runs the self-test 30 seconds after a failure, then backs off to 15 minutes, and goes back to 30 seconds once it passes.

error is a short category, never a stack trace: startup_failed (the signer did not start), <reason>: MarkError (for example tsa_unavailable: MarkError or signer_unavailable: MarkError) or self_test_failed: <ExceptionName>. The full message goes to the server log.

GET /metrics

Prometheus text on the same port. It is open without a token, so keep the port off the public network or scrape it through your reverse proxy. Laidline's series:

Mark routes

Request headers on mark routes

Optional headers on POST /v1/mark/image, /v1/mark/audio and /v1/mark/video label the evidence entry:

A X-Laidline-Route or X-Laidline-Upstream value over 128 characters is ignored, not rejected.

Response headers on a marked file

With on_mark_failure: fail_closed (the default) a mark that fails returns an error, never the unmarked file. With fail_open it returns 200 with the unmarked input and says so in X-Laidline-Warnings.

POST /v1/mark/image

Marks one image and returns it.

curl -s -D - -o marked.png -F file=@photo.png localhost:8080/v1/mark/image

HTTP/1.1 200 OK
x-laidline-asset-id: ast_01M5W41HT36EQ09SZQMERHD503
x-laidline-manifest-id: urn:c2pa:7749ba64-312a-430c-9ff8-e8dfff329b8d
x-laidline-entry-hash: ff2e4240049c2dbbd95e5207ce2517bdd5c65d4af4590bc5e5e825dec090548f
x-laidline-warnings:
content-length: 454191
content-type: image/png

What just happened: Laidline embedded the watermark, signed the Content Credentials, logged an evidence entry and returned the marked PNG in marked.png.

Errors:

POST /v1/mark/audio

Marks one audio file and returns it. Any container PyAV reads is accepted.

The response and headers are those of /v1/mark/image. Errors are the image errors with these differences:

POST /v1/mark/video

Queues one video for marking and answers at once. Video marking is off by default: set watermark.video.enabled: true and install the video extra.

curl -s -X POST -F file=@clip.mp4 localhost:8080/v1/mark/video

{"id":"job_01M5W4...","status":"queued","status_url":"/v1/jobs/job_01M5W4..."}

The status is 202. Errors:

GET /v1/jobs/{id}

Returns the state of a video job. Jobs live in this process and expire after jobs.ttl_hours (24).

{
  "id": "job_01M5W4...",
  "kind": "video",
  "status": "done",
  "created_at": "...",
  "updated_at": "...",
  "expires_at": "...",
  "webhook_url": null,
  "result": {
    "asset_id": "ast_...",
    "manifest_id": "urn:c2pa:...",
    "entry_hash": "...",
    "url": "/v1/assets/...",
    "bytes": 1048576,
    "warnings": [],
    "watermark": {"scheme": "videoseal", "device": "cpu"}
  },
  "error": null,
  "status_url": "/v1/jobs/job_01M5W4..."
}

status is queued, running, done or failed. A failed job has result: null and error: {"reason": "...", "detail": "..."}. Download the marked video from result.url (see GET /v1/assets/{name}). When assets.public_base_url is set the URL is absolute. The webhook receives this same JSON. An unknown or expired job, or a server without video marking, answers 404 with job_not_found.

GET /v1/assets/{name}

Returns a stored marked asset: the output of a video job, or an image the proxy returned as a URL. It answers 200 with the file and Cache-Control: private, max-age=<assets.ttl_hours in seconds>, or 404 {"detail": "asset not found or expired"}.

Detect

POST /detect

POST /v1/detect is an alias. Detection is free and never reads your licence. The request is one of:

curl -s -F file=@marked.png localhost:8080/detect

{"schema":"laidline.detect/1","asset":{"sha256":"5f01f8ef...","mime":"image/png","bytes":454191},"verdict":"marked_by_this_system","grade":"A","signals":[{"type":"c2pa","present":true,"status":"valid_trusted","grade":"A",...}],...}

What just happened: Laidline read the Content Credentials and the watermark and returned the graded result described under The laidline.detect/1 result. Nothing was written to your evidence log.

Errors:

A file Laidline cannot process is not an HTTP error: the answer is 200 with verdict: "error" and a caveat that names the reason.

Detect tokens

In keyed mode (watermark.payload_keys with mode: keyed; laidline init writes it) the response tier depends on the caller. Send the token in the header X-Laidline-Detect-Token. Laidline reads no other header for this, never Authorization, so a gateway token there cannot collide.

The public tier shows grade B or D only, without fingerprints, distances, scores, unconfirmed ids or tag fields. A keyed deployment whose payload keyring did not load serves the public tier to every caller. In unkeyed mode every caller gets the same result. Keys has the full list of what each tier hides.

Rate limits

POST /detect is limited per client address: detect.rate_limit (default 60/min/ip) in a sliding 60-second window. IPv6 clients share a bucket per /64 network. The limit is per server process, not shared across replicas, and a distributed client ignores it, so a public checker also needs a limit at its reverse proxy.

Behind a reverse proxy, set the environment variable FORWARDED_ALLOW_IPS to the proxy's address before you start laidline serve. The server runs on uvicorn, which reads the client address from X-Forwarded-For only for senders in that list (default 127.0.0.1,::1). Otherwise every caller shares the proxy's bucket, or a forged X-Forwarded-For picks one. Optional settings cap a public checker further: detect.media, detect.max_concurrent with detect.max_queued, and detect.daily_limit (Configuration). All are off by default.

CORS

CORS applies to POST /detect and POST /v1/detect only. List the origins that may call it from a browser in detect.cors_origins. Laidline answers the preflight, allows POST, allows no credentials and exposes Retry-After. No other route sends CORS headers, so a page on a listed origin can read detect replies and nothing else. With no origins listed, the server sends no CORS headers.

Signed results

With detect.attest.enabled, a result that names the content's SHA-256 carries an attestation block: the result, signed with your active signing key. A signing failure serves the result unsigned with the caveat result not signed: <reason>. Grading describes the block; laidline verify-result checks it offline.

The laidline.detect/1 result

Every 200 from /detect is a JSON object with these top-level fields:

Every signal has type, present and grade, and most have status. The other fields depend on the type:

The issuer block on a signal says who a mark or credential points to, in the words laidline detect prints (Issuer lines). The public tier removes fields as described above, so code against the fields you need and ignore the rest. A result never says "human-made", "authentic" or "not AI". How each signal earns its grade, and what every field means, is in Grading.

OpenAI-compatible proxy

Point an OpenAI client at http://127.0.0.1:8080/v1. Laidline marks what comes back and forwards everything else unchanged. Details, formats and errors are in OpenAI-compatible proxy.

The client's Authorization header goes upstream (upstream.auth: passthrough, the default) or is replaced with Bearer $OPENAI_API_KEY (upstream.auth: env). Proxy errors use the OpenAI body shape. The upstream's own errors pass through unchanged. Laidline's: 400 invalid_request_error, 500 upstream_auth, 502 upstream_unreachable, upstream_bad_response, upstream_read or adapter_no_match, 504 upstream_timeout, and 503 when marking fails.

Admin routes

Admin routes are for operators, not for your application. They are off until you set the admin token (Authentication) and are not listed in /docs. Use them on a private network or over TLS.

POST /admin/reload

Reloads the signing keys, as SIGHUP does. Answers 200:

{"reloaded": true, "active": "default", "previous": "default", "changed": false, "keys": [{"id": "default", "status": "active"}]}

422 reload_failed when the key file or a chain is invalid; the running keys stay in force. laidline keys rotate --admin-url calls this route.

curl -s -X POST -H "Authorization: Bearer $LAIDLINE_ADMIN_TOKEN" localhost:8080/admin/reload

GET /admin/evidence/status

Returns the evidence writer's health: stream, seq, head, sink_failures (per sink), replica_queue_depth, last_checkpoint (stream, range, ts, status, tsa_gen_time) and signing_key. In keyed mode it adds a detect_state block of counters (tag failures, credential budget use, queue drops). Numbers and ids only.

GET /admin/evidence/export

Streams an evidence bundle (a zip). One export runs at a time, bounded in range and size.

curl -s -H "Authorization: Bearer $LAIDLINE_ADMIN_TOKEN" -o bundle.zip \
  "localhost:8080/admin/evidence/export?from=2026-10-01&to=2026-10-31"

The answer is 200 with Content-Type: application/zip and the header x-laidline-bundle-sha256. Errors:

Limits

The server refuses a mark or detect request whose Content-Length is already over the cap before it reads the body. A body sent without a length is checked while it is read, so a public deployment also caps request bodies at its reverse proxy.

Troubleshooting

Reference

• Command line reference: laidline serve and every other command.
• Configuration: the settings named above.
• Grading: what the grades, verdicts and signals in a detect result mean.
• Keys: the response tiers and detect tokens.
• OpenAI-compatible proxy: the proxy routes in full.
• Evidence: what an exported bundle holds.