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).
/api/v1/domainsThe domains services are served under, the default one first: the server's base domain (source: config) and the connected ones. Each comes with the DNS records that point it at this server and what its last verification found.
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
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/domains" \ -H "Authorization: Bearer $FERRY_TOKEN"[ { "checked_at": "2019-08-24T14:15:22Z", "checks": [ { "kind": "dns", "message": "string", "outcome": "passed" } ], "created_at": "2019-08-24T14:15:22Z", "id": "string", "is_default": true, "name": "string", "source": "config", "status": "pending", "verified_at": "2019-08-24T14:15:22Z", "local": true, "records": [ { "name": "string", "required": true, "type": "string", "value": "string" } ], "served": true, "url_pattern": "string" }]/api/v1/domainsAdds a domain (or a subdomain) of yours. It starts pending: create the records it comes with where its DNS is managed — one wildcard record covers every service. The server then verifies it every few seconds; once its names reach the server it is active, every web service and static site is served at <service>.<name> (with a certificate when the server has HTTPS), and it becomes the default domain if the default one was a local name. A local name (*.localhost, .test…) is served at once.
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
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
POST /api/v1/domains — connect a domain: once its DNS points at this
server, services are served at <service>.<name>.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/domains" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "string" }'{ "checked_at": "2019-08-24T14:15:22Z", "checks": [ { "kind": "dns", "message": "string", "outcome": "passed" } ], "created_at": "2019-08-24T14:15:22Z", "id": "string", "is_default": true, "name": "string", "source": "config", "status": "pending", "verified_at": "2019-08-24T14:15:22Z", "local": true, "records": [ { "name": "string", "required": true, "type": "string", "value": "string" } ], "served": true, "url_pattern": "string"}/api/v1/domains/{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
Domain id or name.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/domains/string" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "checked_at": "2019-08-24T14:15:22Z", "checks": [ { "kind": "dns", "message": "string", "outcome": "passed" } ], "created_at": "2019-08-24T14:15:22Z", "id": "string", "is_default": true, "name": "string", "source": "config", "status": "pending", "verified_at": "2019-08-24T14:15:22Z", "local": true, "records": [ { "name": "string", "required": true, "type": "string", "value": "string" } ], "served": true, "url_pattern": "string"}/api/v1/domains/{id}is_default: true makes it the domain of the URL every service is shown and linked with (url, FERRY_EXTERNAL_URL); the services stay served under the other domains too. Running services read the new FERRY_EXTERNAL_URL at their next deploy or restart.
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
Domain id or name.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
PATCH /api/v1/domains/{id}
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/api/v1/domains/string" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{}'{ "checked_at": "2019-08-24T14:15:22Z", "checks": [ { "kind": "dns", "message": "string", "outcome": "passed" } ], "created_at": "2019-08-24T14:15:22Z", "id": "string", "is_default": true, "name": "string", "source": "config", "status": "pending", "verified_at": "2019-08-24T14:15:22Z", "local": true, "records": [ { "name": "string", "required": true, "type": "string", "value": "string" } ], "served": true, "url_pattern": "string"}/api/v1/domains/{id}The services stop being served under the domain at once (their other hostnames and their custom domains stay), and its certificates are no longer renewed. When it was the default domain, the base domain is again. The DNS records stay where they were created. The base domain of the server (source: config) can't be removed here: it is set by --base-domain.
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
Domain id or name.
Response Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/domains/string" \ -H "Authorization: Bearer $FERRY_TOKEN"/api/v1/domains/{id}/verifyChecks at once, instead of at the server's next pass, whether the names under the domain reach this server: what a made-up name under it resolves to (dns), and whether this server answers a request for it on its public HTTP port (http). The answer is the domain with its new status and checks. A local domain has nothing to verify and is returned as it is.
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
Domain id or name.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/domains/string/verify" \ -H "Authorization: Bearer $FERRY_TOKEN"{ "checked_at": "2019-08-24T14:15:22Z", "checks": [ { "kind": "dns", "message": "string", "outcome": "passed" } ], "created_at": "2019-08-24T14:15:22Z", "id": "string", "is_default": true, "name": "string", "source": "config", "status": "pending", "verified_at": "2019-08-24T14:15:22Z", "local": true, "records": [ { "name": "string", "required": true, "type": "string", "value": "string" } ], "served": true, "url_pattern": "string"}/api/v1/certificatesOne entry per hostname the proxy routes — the dashboard's, then every hostname of every web service and static site (under each served domain, and its custom domains) — with where its certificate stands: issued (and until when), pending or issuing (a new host gets its certificate within seconds of being routed), failed with the reason and the time of the next attempt, local for names no authority certifies, disabled when the server runs without HTTPS.
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
Response Body
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/certificates" \ -H "Authorization: Bearer $FERRY_TOKEN"[ { "error": "string", "expires_at": "2019-08-24T14:15:22Z", "host": "string", "retry_at": "2019-08-24T14:15:22Z", "service": "string", "state": "disabled" }]/api/v1/services/{id}/domainsAn 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.
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/api/v1/services/string/domains" \ -H "Authorization: Bearer $FERRY_TOKEN"[ "string"]/api/v1/services/{id}/domainsWeb services and static sites only. The domain is normalized (lowercase, no trailing dot) and must not be used by another service or be a default host.
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}/domains
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/api/v1/services/string/domains" \ -H "Authorization: Bearer $FERRY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "domain": "string" }'[ "string"]/api/v1/services/{id}/domains/{domain}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.
The custom domain.
Response Body
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/api/v1/services/string/domains/string" \ -H "Authorization: Bearer $FERRY_TOKEN"[ "string"]