FerryDocs
ReferenceAPI reference

Jobs

Job runs: cron runs and one-off commands, with their logs.

List a service's job runs

GET/api/v1/services/{id}/jobs

Cron runs and one-off jobs, newest first.

Authorization

AuthorizationBearer <token>

An API token: one created in the dashboard or by ferry login, or the server token stored in <data-dir>/api_token. GET requests may send it as ?access_token= instead.

In: header

Path Parameters

id*string

Service id or name.

Query Parameters

limit?integer

Maximum number of entries (default 20, clamped to 1..=500).

Formatint32
Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/services/string/jobs" \  -H "Authorization: Bearer $FERRY_TOKEN"
[  {    "command": "string",    "created_at": "2019-08-24T14:15:22Z",    "error": "string",    "exit_code": 0,    "finished_at": "2019-08-24T14:15:22Z",    "id": "string",    "image": "string",    "service_id": "string",    "started_at": "2019-08-24T14:15:22Z",    "status": "pending",    "trigger": "schedule"  }]

Run a job

POST/api/v1/services/{id}/jobs

Runs a one-off command (sh -c) in a new container from the service's live image. Cron jobs run their own command when command is omitted.

Authorization

AuthorizationBearer <token>

An API token: one created in the dashboard or by ferry login, or the server token stored in <data-dir>/api_token. GET requests may send it as ?access_token= instead.

In: header

Path Parameters

id*string

Service id or name.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

POST /api/v1/services/{id}/jobs

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/services/string/jobs" \  -H "Authorization: Bearer $FERRY_TOKEN" \  -H "Content-Type: application/json" \  -d '{}'
{  "command": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "exit_code": 0,  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "service_id": "string",  "started_at": "2019-08-24T14:15:22Z",  "status": "pending",  "trigger": "schedule"}

Get a job run

GET/api/v1/jobs/{job_id}

Authorization

AuthorizationBearer <token>

An API token: one created in the dashboard or by ferry login, or the server token stored in <data-dir>/api_token. GET requests may send it as ?access_token= instead.

In: header

Path Parameters

job_id*string

Job run id.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/jobs/string" \  -H "Authorization: Bearer $FERRY_TOKEN"
{  "command": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "exit_code": 0,  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "service_id": "string",  "started_at": "2019-08-24T14:15:22Z",  "status": "pending",  "trigger": "schedule"}

Cancel a job run

POST/api/v1/jobs/{job_id}/cancel

Stops a pending or running job (status canceled).

Authorization

AuthorizationBearer <token>

An API token: one created in the dashboard or by ferry login, or the server token stored in <data-dir>/api_token. GET requests may send it as ?access_token= instead.

In: header

Path Parameters

job_id*string

Job run id.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/jobs/string/cancel" \  -H "Authorization: Bearer $FERRY_TOKEN"
{  "command": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "exit_code": 0,  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "service_id": "string",  "started_at": "2019-08-24T14:15:22Z",  "status": "pending",  "trigger": "schedule"}

Job logs (SSE)

GET/api/v1/jobs/{job_id}/logs

Authorization

AuthorizationBearer <token>

An API token: one created in the dashboard or by ferry login, or the server token stored in <data-dir>/api_token. GET requests may send it as ?access_token= instead.

In: header

Path Parameters

job_id*string

Job run id.

Query Parameters

follow?boolean

Keep streaming new lines until the deploy or job finishes (instead of only the stored log).

Response Body

text/event-stream

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/jobs/string/logs" \  -H "Authorization: Bearer $FERRY_TOKEN"
"event: log\ndata: {\"ts\":\"2026-01-01T12:00:00Z\",\"stream\":\"system\",\"line\":\"==> Build succeeded\"}\n\nevent: end\ndata: \n\n"

Domains

The domains services are served under — <service>.<domain> for every web service and static site: the server's base domain and the domains connected to it, each pointed at the server with one wildcard DNS record and verified by the server — the certificates of the routed hostnames, and the custom domains of one service (unique across services).

Datastores

Managed Postgres and Redis instances with their connection strings and resource limits.