FerryDocs
ReferenceAPI reference

Deploys

Deploy history, manual deploys, source uploads (ferry up), cancellation and build logs.

List a service's deploys

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

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/deploys" \  -H "Authorization: Bearer $FERRY_TOKEN"
[  {    "commit_message": "string",    "commit_sha": "string",    "created_at": "2019-08-24T14:15:22Z",    "error": "string",    "finished_at": "2019-08-24T14:15:22Z",    "id": "string",    "image": "string",    "port": 0,    "service_id": "string",    "source": {      "branch": "string",      "commit": "string",      "kind": "git",      "repo_url": "string"    },    "started_at": "2019-08-24T14:15:22Z",    "status": "queued",    "trigger": "create"  }]

Deploy a service

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

Queues a manual deploy of the configured source: the branch head (or commit) of the repository, or the image. An empty body deploys with the defaults.

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}/deploys

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/services/string/deploys" \  -H "Authorization: Bearer $FERRY_TOKEN" \  -H "Content-Type: application/json" \  -d '{}'
{  "commit_message": "string",  "commit_sha": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "port": 0,  "service_id": "string",  "source": {    "branch": "string",    "commit": "string",    "kind": "git",    "repo_url": "string"  },  "started_at": "2019-08-24T14:15:22Z",  "status": "queued",  "trigger": "create"}

Deploy uploaded source code

POST/api/v1/services/{id}/deploys/upload

Deploys a .tar.gz of the source tree (what ferry up sends) to a service without a repository or image; the deploy has trigger upload and an archive source.

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

clear_cache?boolean

Build without the build cache.

Request Body

application/gzip

The raw gzip-compressed tar archive (at most 512 MiB).

TypeScript Definitions

Use the request body type in TypeScript.

body*file

A gzip-compressed tar archive of the source tree (.tar.gz, at most 512 MiB).

Formatbinary

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/services/string/deploys/upload" \  -H "Authorization: Bearer $FERRY_TOKEN" \  -H "Content-Type: application/gzip" \  -d 'string'
{  "commit_message": "string",  "commit_sha": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "port": 0,  "service_id": "string",  "source": {    "branch": "string",    "commit": "string",    "kind": "git",    "repo_url": "string"  },  "started_at": "2019-08-24T14:15:22Z",  "status": "queued",  "trigger": "create"}

Get a deploy

GET/api/v1/deploys/{deploy_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

deploy_id*string

Deploy id.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/api/v1/deploys/string" \  -H "Authorization: Bearer $FERRY_TOKEN"
{  "commit_message": "string",  "commit_sha": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "port": 0,  "service_id": "string",  "source": {    "branch": "string",    "commit": "string",    "kind": "git",    "repo_url": "string"  },  "started_at": "2019-08-24T14:15:22Z",  "status": "queued",  "trigger": "create"}

Cancel a deploy

POST/api/v1/deploys/{deploy_id}/cancel

Stops a queued or running deploy (status canceled); the live deploy keeps serving.

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

deploy_id*string

Deploy id.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v1/deploys/string/cancel" \  -H "Authorization: Bearer $FERRY_TOKEN"
{  "commit_message": "string",  "commit_sha": "string",  "created_at": "2019-08-24T14:15:22Z",  "error": "string",  "finished_at": "2019-08-24T14:15:22Z",  "id": "string",  "image": "string",  "port": 0,  "service_id": "string",  "source": {    "branch": "string",    "commit": "string",    "kind": "git",    "repo_url": "string"  },  "started_at": "2019-08-24T14:15:22Z",  "status": "queued",  "trigger": "create"}

Build and deploy logs (SSE)

GET/api/v1/deploys/{deploy_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

deploy_id*string

Deploy 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/deploys/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"

Services

Web services, private services, background workers, static sites and cron jobs: CRUD, lifecycle actions (restart, suspend, resume, scale, rollback), status and runtime logs.

Environment variables

A service's own environment variables. ?restart=true restarts the live service when its effective environment changed.