The Creato API

Quick start

Make a key from your account, under Developers. It is shown once; keep it on your server, never in a browser or an app. Then check it works:

export CREATO_URL="https://your-creato-address"
export CREATO_KEY="crk_…"   # from your account, under Developers

curl -s "$CREATO_URL/api/v1/me" \
  -H "Authorization: Bearer $CREATO_KEY"

The API answers JSON, in the same camelCase names as the Brand Spec. Steps that use the design model take a few seconds to a minute and answer when they are done.

Authentication

Send the key as Authorization: Bearer crk_… on every request. A key acts as the account that made it: it starts brands on that account's kits, or as free previews when it holds none, and sees only that account's brands. Anything the account could not do in the browser, the key cannot do either. An account holds up to 10 keys; revoking one stops it at once.

Making a brand

The same steps as on Creato, in order. GET /api/v1/brands/:id always says which comes next in next.

1. 1. Start the brand from the idea, in the founder's words. It runs on a kit the account holds, or as a free preview: up to 3 waiting at once, with the interview, the first names and the first directions free.
2. 2. Answer the interview. The questions come back with the brand, each with its type and where it writes in the Brand Spec. Send what you have; the answer says what is missing.
3. 3. Names, then a name. Twenty candidates with domain checks, or the founder's own.
4. 4. Directions, then one. Three complete looks, each with tokens and a logo system.
5. 5. The kit. The look is always there; the files and token exports come with a kit. A free preview is unlocked with a kit the account holds (POST …/unlock); kits are bought on Creato.

curl -s -X POST "$CREATO_URL/api/v1/brands" \
  -H "Authorization: Bearer $CREATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "idea": "A mobile dog grooming van in Austin" }'

export BRAND="…"   # brand.id from the response

{
  "brand": { "id": "6f1c…", "name": null, "status": "draft", "plan": "preview", … },
  "extraction": { "offering": "Mobile dog grooming", "category": "services_local", "place": "Austin, Texas", … },
  "interview": {
    "questions": [
      { "id": "offering", "prompt": "What you do, in one line", "type": { "kind": "free_text", … },
        "writesTo": "positioning.offering", "answered": false, "value": "Mobile dog grooming" },
      …
    ]
  }
}

curl -s -X POST "$CREATO_URL/api/v1/brands/$BRAND/spec" \
  -H "Authorization: Bearer $CREATO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "answers": {
        "offering": "Salon quality dog grooming at your door",
        "audience": "Busy Austin pet owners",
        "feel_words": ["cared for", "delighted", "relieved"],
        "personality": { "warmth": 25, "playfulness": 35, "modernity": 60, "boldness": 55 },
        "price_position": "premium",
        "has_name": "propose",
        "primary_goal": "book",
        "secondary_page": "services"
      } }'
# → { "done": true, "spec": { … }, "version": 1 }  or  { "done": false, "missing": ["…"] }

curl -s -X POST "$CREATO_URL/api/v1/brands/$BRAND/names" -H "Authorization: Bearer $CREATO_KEY"
# → { "names": [ { "name": "Doorwag", "strategy": "compound", "scores": { … }, "availability": { … } }, … ] }

curl -s -X PUT "$CREATO_URL/api/v1/brands/$BRAND/name" \
  -H "Authorization: Bearer $CREATO_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Doorwag" }'

curl -s -X POST "$CREATO_URL/api/v1/brands/$BRAND/directions" -H "Authorization: Bearer $CREATO_KEY"
# → { "directions": [ { "id": "d1", "name": "…", "rationale": "…", "tokens": { … },
#       "logo": { "primary": { "svg": "<svg …>" }, "icon": { … }, "colors": { … } } }, … ] }

curl -s -X PUT "$CREATO_URL/api/v1/brands/$BRAND/direction" \
  -H "Authorization: Bearer $CREATO_KEY" -H "Content-Type: application/json" \
  -d '{ "directionId": "d2" }'

curl -s "$CREATO_URL/api/v1/brands/$BRAND/kit" -H "Authorization: Bearer $CREATO_KEY"
# → { "unlocked": true, "spec": { … }, "direction": { "tokens": { … }, "logo": { … } },
#     "exports": { "css": "…", "tailwind": "…", "dtcg": { … } },
#     "files": [ { "file": "logo.svg", "url": "/api/v1/brands/…/files/logo.svg", "locked": false }, … ] }

curl -s -o logo.svg "$CREATO_URL/api/v1/brands/$BRAND/files/logo.svg" -H "Authorization: Bearer $CREATO_KEY"

A second names or directions run spends one of the kit's regenerations, as on Creato; Studio makes them unlimited, and a free preview has none.

Endpoints

Steps marked model call the design model and count against the daily allowance (see Limits).

• GET/api/v1/meThe key's account: kits held, free previews open, Studio, today's use, and its workspaces with its role in each.
• GET/api/v1/brandsThe account's brands, newest first; ?workspace=<id> for a workspace it belongs to.
• POST/api/v1/brandsStart a brand from an idea: on a kit the account holds, or as a free preview. With workspaceId, in that workspace, on its kits.model
• GET/api/v1/brands/:idWhere the brand is (next: interview, names, directions or kit) and what it has.
• GET/api/v1/brands/:id/interviewThe questions this brand is asked, with types and starting values.
• POST/api/v1/brands/:id/specSend answers. When they are complete, the Brand Spec is written.model
• GET/api/v1/brands/:id/specThe latest Brand Spec and its version.
• POST/api/v1/brands/:id/namesTwenty ranked names with domain checks.model
• GET/api/v1/brands/:id/namesThe latest names and the one chosen.
• PUT/api/v1/brands/:id/nameChoose a name, from the list or your own.
• POST/api/v1/brands/:id/directionsThree complete visual directions, each with tokens and a logo system.model
• GET/api/v1/brands/:id/directionsThe directions proposed so far and the one chosen.
• PUT/api/v1/brands/:id/directionChoose a direction (d1, d2, d3…).
• POST/api/v1/brands/:id/unlockUnlock a free preview with a kit the account holds.
• GET/api/v1/brands/:id/kitThe kit: spec, tokens, logo system as SVG, exports and the file list.
• GET/api/v1/brands/:id/files/:fileOne of the kit's files (below). A free preview has none.

Files

• logo.svg
• logo-one-color.svg
• logo-horizontal.svg
• logo-reversed.svg
• wordmark.svg
• icon.svg
• favicon.svg
• logo.png
• icon.png
• guidelines.pdf
• tokens.css
• tailwind.css
• tokens.json
• brand-spec.json
• canva.zip

Engine endpoints

One engine on what you send, without making a brand: read an idea, name a brief, compile a design system or draw wordmarks from a Brand Spec. They are part of Studio, which is unlimited asset generation; without it they answer 402.

• POST/api/v1/engines/extractRead an idea: offering, category, audience, place, name hints.model
• POST/api/v1/engines/namesNames for a brief or an idea, without making a brand.model
• POST/api/v1/engines/design-systemThe Design System Compiler on a Brand Spec: tokens, CSS, Tailwind, DTCG.
• POST/api/v1/engines/wordmarkWordmarks and an icon mark for a Brand Spec, gated for legibility.

curl -s -X POST "$CREATO_URL/api/v1/engines/design-system" \
  -H "Authorization: Bearer $CREATO_KEY" -H "Content-Type: application/json" \
  -d "{ \"spec\": $(cat brand-spec.json) }"
# → { "tokens": { … }, "exports": { "css": "…", "tailwind": "…", "dtcg": { … } } }

Errors

Every error is { error: { code, message, requestId } }, with the status below. The message is written to be shown to a founder. Every response carries x-request-id; quote it if you write to us.

HTTP/1.1 402 Payment Required
x-request-id: req_Zk3…

{ "error": { "code": "payment_required",
             "message": "Unlock the kit to ask for more. The first names and directions are part of the free preview.",
             "requestId": "req_Zk3…" } }

Limits

• 60 requests a minute per key. Headers x-ratelimit-limit and x-ratelimit-remaining say where you are.
• 100 model requests a day per account, across all its keys, renewed at midnight UTC. Model steps also send x-model-requests-remaining. Requests refused before the work (a bad body, a 402) do not count.
• Over either limit the API answers 429 with Retry-After, in seconds.

The Brand Spec

Every Creato engine takes a Brand Spec: positioning, business facts, audience, personality, voice, visual direction, name, website and constraints. It is published as JSON Schema, version 1. The kit's brand-spec.json is a Brand Spec; so is what the spec endpoints return.

• /api/v1/brand-spec.schema.json the document, as Creato stores and sends it
• /api/v1/brand-spec.input.schema.json what the engine endpoints accept: fields with defaults may be left out