API Reference

Every alias is called through a single endpoint. Clients authenticate with a JWT or API key; FExec validates parameters against the alias's rules, executes it, and returns the result.

Every running instance also serves live, interactive OpenAPI documentation for this fixed endpoint shape at GET /apidocs/ (Swagger UI) and GET /openapi.json (raw spec) — it does not enumerate your specific aliases, since those are operator-defined.

Authentication
Endpoint & request body
Response codes
Example

Every requestAuthentication

Every request must include one of:

Header	Value
`Authorization`	`Bearer <JWT>`
`X-API-Key`	`<key>`

JWTs are validated against operator-configured public keys; the token's sub and aliases claims determine identity and permitted aliases, merged with any matching user configuration. See Authentication configuration for how users, API keys, and JWT public keys are defined.

Calling an aliasEndpoint & request body

POST /v1/{alias_name}

Parameters can be sent in any of the following formats:

JSON application/json

{ "param1": "value1", "param2": "value2" }

Form-encoded application/x-www-form-urlencoded

param1=value1&param2=value2

Multipart form multipart/form-data

-F param1=value1 -F param2=value2

URL query string url-encoded

POST /v1/{alias_name}?param1=value1&param2=value2

A request with no body (absent or zero Content-Length) is always treated as having no parameters, regardless of the Content-Type header. A request with a non-zero body and an unrecognised Content-Type is rejected with 400. Query string parameters are merged with body parameters before validation; a parameter supplied by both the query string and the body is rejected with 400.

What comes backResponse codes

Code	Meaning
200	Success — body contains the alias output. Also returned when the command exited non-zero but the alias's `exitCodeMap` explicitly maps that exit code to 200.
400	Bad request — missing/invalid/extra parameters.
401	Missing or invalid credentials.
403	Credentials valid but alias not permitted for this user.
404	Alias does not exist.
408	Execution timed out and the process/container was killed by FExec.
422	Command completed but exited with a non-zero code (default; overridable per alias via `exitCodeMap`).
500	Command executed but failed internally (infrastructure-level failure, e.g. Docker unreachable).
503	Service is shutting down.

200 from FExec means both FExec and the invoked process/container succeeded — not merely that FExec was able to run it — except when exitCodeMap has explicitly reassigned that exit code's status. See Exit Code Status Mapping.

Putting it togetherExample

curl -X POST https://your-fexec-host/v1/generate-report \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -d '{"type": "pdf", "date": "2024-01-15"}'

For the full set of aliases exposed by a given deployment, ask the operator — the alias catalog is configuration, not something FExec advertises publicly.