​

Resource IDs

​

Prefixes

​

The two strictness rules

​

Body fields — strict (prefixed only)

# GOOD
curl -X POST https://api.moda.app/v1/remix \
  -H "Authorization: Bearer moda_live_..." \
  -H "Moda-Version: 2026-05-01" \
  -H "Content-Type: application/json" \
  -d '{"canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV"}'

# BAD — 400 invalid_request
curl -X POST https://api.moda.app/v1/remix \
  -H "..." \
  -d '{"canvas_id": "550e8400-e29b-41d4-a716-446655440000"}'

​

Path parameters — tolerant (either form)

# BOTH WORK
curl -X POST https://api.moda.app/v1/canvases/cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV/export ...
curl -X POST https://api.moda.app/v1/canvases/550e8400-e29b-41d4-a716-446655440000/export ...

​

Why this design

• Prefixed IDs are self-describing. Pasting one in a log or a PR makes it immediately clear what kind of object it is.
• Strictness in bodies prevents accidental cross-resource confusion (passing a canvas_id where a brand_kit_id was expected — the server catches it at validation).
• Tolerance in paths avoids breaking older callers who already hold bare UUIDs.

​

In responses

{
  "id": "task_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "kind": "design",
  "result": {
    "canvas_id": "cvs_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
    "canvas_url": "https://moda.app/canvas/..."
  }
}

​

Webhook payloads

{
  "id": "evt_01HT9WK8N3M2J4A5Z6P7Q8R9TV",
  "type": "task.succeeded",
  "created": "2026-04-15T12:01:00+00:00",
  "api_version": "2026-05-01",
  "data": { "id": "task_01HT9WK8N3M2J4A5Z6P7Q8R9TV", ... }
}

​

Common wrong guesses

• Sending a bare UUID in a JSON body. 400 invalid_request. Always use prefixed IDs in bodies.
• Storing bare UUIDs from older responses. They work in path params today, but storing the prefixed form (from any current response) is safer for future use.
• Parsing the prefix at the client to dispatch on resource type. Don’t — use the kind field on task envelopes or the response shape. Prefixes are for humans.
• Assuming upl_ and file_ are interchangeable. upl_ is legacy; current uploads return file_. Don’t mix.

​

Upstream