Env groups
Shared variable sets linked to services (a service's own variables win over its groups'), and linking / unlinking them.
/api/v1/env-groupsAn 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
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/env-groups" \ -H "Authorization: Bearer $FERRY_TOKEN"[ { "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "updated_at": "2019-08-24T14:15:22Z", "services": [ "string" ], "vars": [ { "key": "string", "value": "string" } ] }]/api/v1/env-groupsAn 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
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/env-groups
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/env-groups" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "updated_at": "2019-08-24T14:15:22Z", "services": [ "string" ], "vars": [ { "key": "string", "value": "string" } ]}/api/v1/env-groups/{id}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
Env group id or name.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/env-groups/string" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "updated_at": "2019-08-24T14:15:22Z", "services": [ "string" ], "vars": [ { "key": "string", "value": "string" } ]}/api/v1/env-groups/{id}Refused while services are linked to it (they would lose its variables at their next restart), unless force=true; restart=true then restarts the linked live services so they drop the variables now.
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
Env group id or name.
Query Parameters
Delete even though services are linked to it.
With force: restart the linked live services whose environment changes.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/env-groups/string" \ -H "Authorization: Bearer $FERRY_TOKEN"/api/v1/env-groups/{id}/envUpserts set and deletes unset; the other variables stay.
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
Env group id or name.
Query Parameters
Then restart the affected live services whose effective environment changed (the variables are saved either way; a failed restart is reported as the error).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
PATCH /api/v1/services/{id}/env (and env groups): upsert set, delete unset.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/api/v1/env-groups/string/env" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "updated_at": "2019-08-24T14:15:22Z", "services": [ "string" ], "vars": [ { "key": "string", "value": "string" } ]}/api/v1/env-groups/{id}/envThe group's variables become exactly vars, validated alone and in the combined environment of every linked service.
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
Env group id or name.
Query Parameters
Then restart the affected live services whose effective environment changed (the variables are saved either way; a failed restart is reported as the error).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
PUT /api/v1/services/{id}/env (replace all) and env group equivalent.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/v1/env-groups/string/env" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "vars": [ { "key": "string", "value": "string" } ] }'{ "created_at": "2019-08-24T14:15:22Z", "id": "string", "name": "string", "updated_at": "2019-08-24T14:15:22Z", "services": [ "string" ], "vars": [ { "key": "string", "value": "string" } ]}/api/v1/services/{id}/env-groupsThe group's variables apply from the service's next deploy or restart (its own variables win). Linking an already linked group is a no-op.
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
Service id or name.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/services/{id}/env-groups
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/services/string/env-groups" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "group": "string" }'{ "auto_deploy": true, "branch": "string", "build_command": "string", "cpu_limit": 0, "created_at": "2019-08-24T14:15:22Z", "custom_domains": [ "string" ], "deploy_hook_key": "string", "disk_mount_path": "string", "dockerfile_path": "string", "health_check_path": "string", "id": "string", "image": "string", "instances": 0, "live_deploy_id": "string", "memory_limit_mb": 0, "name": "string", "port": 0, "publish_dir": "string", "repo_url": "string", "root_dir": "string", "runtime": "auto", "schedule": "string", "start_command": "string", "suspended": true, "type": "web_service", "updated_at": "2019-08-24T14:15:22Z", "deploy_hook_path": "string", "env_groups": [ "string" ], "hosts": [ "string" ], "internal_host": "string", "internal_port": 0, "latest_deploy": { "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" }, "state": "not_deployed", "url": "string"}/api/v1/services/{id}/env-groups/{group}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
Service id or name.
Env group id or name.
Response Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/services/string/env-groups/string" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "auto_deploy": true, "branch": "string", "build_command": "string", "cpu_limit": 0, "created_at": "2019-08-24T14:15:22Z", "custom_domains": [ "string" ], "deploy_hook_key": "string", "disk_mount_path": "string", "dockerfile_path": "string", "health_check_path": "string", "id": "string", "image": "string", "instances": 0, "live_deploy_id": "string", "memory_limit_mb": 0, "name": "string", "port": 0, "publish_dir": "string", "repo_url": "string", "root_dir": "string", "runtime": "auto", "schedule": "string", "start_command": "string", "suspended": true, "type": "web_service", "updated_at": "2019-08-24T14:15:22Z", "deploy_hook_path": "string", "env_groups": [ "string" ], "hosts": [ "string" ], "internal_host": "string", "internal_port": 0, "latest_deploy": { "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" }, "state": "not_deployed", "url": "string"}Environment variables
A service's own environment variables. ?restart=true restarts the live service when its effective environment changed.
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).