Delicious

REST API

Preview. This is the planned v1 surface — not yet live. Shapes may change before launch.

Base URL https://api.delicious.works/v1. All requests carry Authorization: Bearer dk_live_… (or dk_test_… for the sandbox).

Conventions

  • Versioned under /v1; additive changes only within a version.
  • Idempotency: send an Idempotency-Key header on POST /v1/runs so a retried request never starts two runs.
  • Pagination: opaque cursor + limit.
  • Errors: { error: { type, code, message, field? } } with a conventional HTTP status.
  • Rate limits: X-RateLimit-* headers; 429 with Retry-After.

Runs

  • POST /v1/runs — create a run.
  • GET /v1/runs/{id} — fetch status.
  • GET /v1/runs — list (filter by status, cursor-paginated).
  • POST /v1/runs/{id}/cancel — cancel.

Create an idea-mode run:

POST /v1/runs
Authorization: Bearer dk_live_…
Idempotency-Key: 8f3c…

{
  "mode": "idea",
  "idea": {
    "pitch": "A calm habit tracker for parents",
    "audience": "busy parents of young kids",
    "monetization": "freemium"
  }
}

Returns a run:

{
  "id": "run_3kZ9…",
  "mode": "idea",
  "status": "running",
  "stage": "02_spec",
  "gate_pending": null,
  "app_id": null,
  "created_at": "2026-06-30T12:00:00Z"
}

For ship mode, send "mode": "ship" with a source (a repo URL or an App Spec) instead of idea.

Spec

  • GET /v1/runs/{id}/spec — the App Spec (see the schema).
  • PATCH /v1/runs/{id}/spec — edit before or at a gate (idempotent merge).

Gates

  • GET /v1/runs/{id}/gates — list the three gates and their state.
  • POST /v1/runs/{id}/gates/{gate}:approve — approve. gate is idea, brand, or final.
  • POST /v1/runs/{id}/gates/{gate}:reject — reject with { "notes": "…" }; sends the run back to the relevant stage.

Artifacts

  • GET /v1/runs/{id}/artifacts — the manifest.
  • GET /v1/runs/{id}/artifacts/{kind} — kind is screenshots, ipa, metadata, scorecard, preflight, or spec. Binaries return short-lived signed URLs.
  • GET /v1/runs/{id}/scorecard — the Deliciousness scores + the pre-flight result.

Live

  • GET /v1/runs/{id}/events — a Server-Sent Events stream of stage transitions and build/QA logs.

For push instead of poll, register a webhook.