API Reference

Authentication

All API requests require a Bearer token. Create tokens in your dashboard at gethatch.eu/dashboard/tokens.

Authorization: Bearer <your-api-token>

Base URL

https://api.gethatch.eu/

All API endpoints are served via Nuxt server routes at this base path.

POST /deploy

Trigger a new deployment for an existing egg. Typically deployments are triggered by hatch deploy, but you can also trigger them via the API.

POST https://api.gethatch.eu/deploy
Authorization: Bearer <token>
Content-Type: application/json

{
  "project": "myapp",
  "env": {
    "DATABASE_URL": "postgres://...",
    "API_KEY": "sk-..."
  }
}

Response:

{
  "id": "deploy_abc123",
  "status": "building",
  "url": "https://myapp-xxxx.nest.gethatch.eu",
  "created_at": "2025-01-15T10:30:00Z"
}

GET /deployments

List all deployments for your account.

GET https://api.gethatch.eu/deployments
Authorization: Bearer <token>

Query parameters:

PATCH /apps/:slug/resources

Override an egg's resource limits. Requires authentication and ownership. Available from hatch-api vNEXT.

PATCH https://api.gethatch.eu/apps/myapp/resources
Authorization: Bearer <token>
Content-Type: application/json

{
  "memory_mb": 768
}

Overrides win over the runtime profile and are capped by tier (free 512 MB, Always On 1024 MB). Requests beyond the cap return 422. Changes apply on the next deploy, restart or wake.

POST /billing/energy-pack/checkout

Create a Stripe Checkout session for an Energy Pack (1,000 non-expiring minutes). Requires authentication. Available from hatch-api vNEXT.

POST https://api.gethatch.eu/billing/energy-pack/checkout
Authorization: Bearer <token>

Response:

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_..."
}

Open the URL to complete the payment. Pack minutes are credited by the Stripe webhook idempotently (a session is only ever credited once), and appear in the pack balance of hatch energy. Consumption order: daily → weekly → bonus → pack.

GET /deployments/:id

Get details of a specific deployment.

GET https://api.gethatch.eu/deployments/deploy_abc123
Authorization: Bearer <token>

DELETE /deployments/:id

Delete a deployment and remove it from your project.

DELETE https://api.gethatch.eu/deployments/deploy_abc123
Authorization: Bearer <token>

POST /v1/apps/{slug}/previews

Create or update a preview environment. 4th concurrent preview returns 422.

POST https://api.gethatch.eu/v1/apps/myapp-xxxx/previews
Authorization: Bearer <token>
Content-Type: application/json

{
  "pr_number": 42
}

POST /v1/apps/{slug}/webhooks

Register a deploy webhook. Response includes the signing secret once. https URLs only, private/loopback IPs rejected, max 3 per egg (422).

POST https://api.gethatch.eu/v1/apps/myapp-xxxx/webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com/hooks/deploys",
  "events": ["deploy"]
}

GET /v1/apps/{slug}/previews

List preview environments: slug, pr_number, url, status, expires_at.

DELETE /v1/apps/{slug}/previews/{pr}

Tear down the preview for a PR number (routes, database, addons — full delete).

GET /v1/apps/{slug}/webhooks

List webhooks (urls, events, active, last delivery status — never the secret).

DELETE /v1/apps/{slug}/webhooks/{id}

Remove a webhook.

POST /v1/apps/{slug}/webhooks/{id}/test

Send a signed ping event to the webhook URL.

GET /deployments/:id/logs

Retrieve build and runtime logs for a deployment.

GET https://api.gethatch.eu/deployments/deploy_abc123/logs
Authorization: Bearer <token>

Query parameters:

POST /v1/apps/:slug/volume

Provision or resize the app's persistent volume, mounted at /data on the next deploy. Returns 422 when size_mb is over the tier cap (1024 MB free, 5120 MB always-on).

POST https://api.gethatch.eu/v1/apps/my-app/volume
Authorization: Bearer <token>
Content-Type: application/json

{ "size_mb": 1024 }

GET /v1/apps/:slug/volume

Return the volume's size, usage, mount point, and status (active or grace_deleting).

GET https://api.gethatch.eu/v1/apps/my-app/volume
Authorization: Bearer <token>

Response:

{
  "size_mb": 1024,
  "used_mb": 37,
  "status": "active",
  "mount": "/data",
  "over_quota": false
}

POST /v1/apps/{slug}/crons

Create a scheduled task (cron) for an app. The command runs on the given 5-field cron schedule (UTC).

POST https://api.gethatch.eu/v1/apps/{slug}/crons
Authorization: Bearer <token>
Content-Type: application/json

{
  "schedule": "*/5 * * * *",
  "command": "npm run digest"
}

Response:

{
  "id": "cron_abc123",
  "schedule": "*/5 * * * *",
  "command": "npm run digest",
  "enabled": true,
  "created_at": "2026-01-15T10:30:00Z"
}

DELETE /v1/apps/:slug/volume

Detach the volume; its data is erased after a 7-day grace period. Pass ?now=true to delete immediately and irreversibly.

DELETE https://api.gethatch.eu/v1/apps/my-app/volume?now=true
Authorization: Bearer <token>

GET /v1/apps/{slug}/crons

List all scheduled tasks for an app, including each cron's last and next run.

GET https://api.gethatch.eu/v1/apps/{slug}/crons
Authorization: Bearer <token>

DELETE /v1/apps/{slug}/crons/{id}

Delete a scheduled task. The periodic job is removed and no further runs are scheduled.

DELETE https://api.gethatch.eu/v1/apps/{slug}/crons/{id}
Authorization: Bearer <token>

GET /v1/apps/{slug}/crons/{id}/runs

List recent runs for a scheduled task (most recent first): status, exit code, and timestamps. Statuses are running, success, failed, or skipped_depleted (the run was skipped because the energy budget was depleted).

GET https://api.gethatch.eu/v1/apps/{slug}/crons/{id}/runs
Authorization: Bearer <token>