Ship API
The REST API that powers all ShipStatic interfaces. Everything the Web, CLI, and SDK can do, the API can do directly.
https://api.shipstatic.com
Authentication
Requires an API Key or deploy token. Pass credentials via the Authorization header. The prefix determines the credential type:
| Method | Format | Use case |
|---|---|---|
| API key | Bearer ship-{64 hex} |
Persistent access |
| Deploy token | Bearer token-{64 hex} |
Single-use deploy |
When both are present, the deploy token takes precedence.
Endpoints
Deployments
| Method | Path | Description |
|---|---|---|
POST |
/deployments |
Upload a new deployment (multipart) |
GET |
/deployments |
List all deployments |
GET |
/deployments/:id |
Get deployment details |
PATCH |
/deployments/:id |
Update labels |
DELETE |
/deployments/:id |
Delete deployment (async) |
Domains
| Method | Path | Description |
|---|---|---|
PUT |
/domains/:name |
Create, link, switch, or label (upsert) |
GET |
/domains |
List all domains |
GET |
/domains/:name |
Get domain details |
DELETE |
/domains/:name |
Delete domain |
POST |
/domains/:name/validate |
Pre-flight availability check |
POST |
/domains/:name/verify |
Trigger DNS verification |
GET |
/domains/:name/dns |
Required DNS records |
GET |
/domains/:name/records |
Current live DNS records |
GET |
/domains/:name/share |
Shareable DNS setup link |
Tokens
| Method | Path | Description |
|---|---|---|
POST |
/tokens |
Create token |
GET |
/tokens |
List all tokens |
DELETE |
/tokens/:token |
Revoke token |
Account
| Method | Path | Description |
|---|---|---|
GET |
/account |
Get current account |
GET |
/config |
Platform config and plan limits |
GET |
/ping |
Health check |
Status Codes
| Code | Meaning | Example |
|---|---|---|
200 |
Success | Read, update, synchronous delete |
201 |
Created | POST /deployments, POST /tokens |
202 |
Accepted | DELETE /deployments/:id (async cleanup) |
400 |
Validation error | Invalid input, missing fields |
401 |
Authentication error | Missing or invalid credentials |
404 |
Not found | Resource doesn't exist or belongs to another account |
422 |
Business rule | Account suspended, resource limit exceeded |
429 |
Rate limited | Too many requests |
Conventions
Content type. All requests and responses use application/json, except deployment upload which uses multipart/form-data.
Domain names in paths are URL-encoded. The API normalizes casing and Unicode.
Async operations. Only deployment deletion is asynchronous (returns 202). All other deletes are synchronous (200).
Errors return a consistent shape:
{
"error": "Deployment not found",
"type": "not_found",
"status": 404
}