API Reference

REST API for the Shipyard platform. Base URL: https://api.shipyard.wtf

Authentication

All authenticated endpoints require a Bearer token in theAuthorization header. Tokens are either Privy JWTs (from the dashboard) or API tokens (from shipyard login, prefixed with shp_).

Response format

All responses follow this envelope:

// Success
{ "ok": true, "data": { ... } }

// Error
{ "ok": false, "error": { "code": "NOT_FOUND", "message": "..." } }

Health

GET/health

Health check endpoint.

Response

{ "ok": true, "version": "0.1.0" }

Auth

POST/auth/loginAuth required

Response

{ "ok": true, "data": { "id": "did:privy:...", "email": "...", "plan": "free" } }

POST/auth/tokensAuth required

Create an API token for CLI authentication.

Request body

{ "name": "my-laptop" }

Response

{ "ok": true, "data": { "id": "...", "name": "my-laptop", "token": "shp_..." } }

GET/auth/tokensAuth required

List API tokens (token values are not returned).

DELETE/auth/tokens/:idAuth required

Revoke an API token.

Users

GET/users/meAuth required

Get the current authenticated user's profile.

Response

{ "ok": true, "data": { "id": "...", "email": "...", "plan": "free", "address": "0x..." } }

PATCH/users/meAuth required

Update the current user's profile.

Request body

{ "displayName": "Jeremy", "avatarUrl": "https://..." }

Projects

GET/projectsAuth required

List all projects for the authenticated user.

POST/projectsAuth required

Create a new project.

Request body

{ "name": "my-app", "framework": "astro", "region": "iad" }

Response

{ "ok": true, "data": { "id": "...", "name": "my-app", "framework": "astro", "status": "active" } }

GET/projects/:idAuth required

Get a project by ID.

PATCH/projects/:idAuth required

Update a project.

Request body

{ "displayName": "My App", "framework": "next" }

DELETE/projects/:idAuth required

Soft-delete a project (sets status to 'deleted').

Deployments

GET/projects/:id/deploymentsAuth required

List deployments for a project, ordered by creation date.

POST/projects/:id/deploymentsAuth required

Create a deployment. Triggers Fly.io machine provisioning.

Request body

{ "artifactKey": "users/.../artifact.tar.gz", "framework": "astro", "commitSha": "abc123" }

POST/projects/:id/deployments/:deployId/promoteAuth required

Promote a deployment to production.

Domains

GET/projects/:id/domainsAuth required

List domains for a project.

POST/projects/:id/domainsAuth required

Add a custom domain. Returns a TXT record for verification.

Request body

{ "domain": "app.example.com" }

POST/projects/:id/domains/:domainId/verifyAuth required

Verify domain ownership via DNS TXT lookup.

DELETE/projects/:id/domains/:domainIdAuth required

Remove a custom domain.

Storage

POST/storage/presignAuth required

Get a presigned upload URL for S3.

Request body

{ "key": "users/.../artifact.tar.gz", "contentType": "application/gzip" }

Response

{ "ok": true, "data": { "url": "https://s3.../presigned", "key": "..." } }

GET/storage/presign/:keyAuth required

Get a presigned download URL.