Quickstart

From a token to rendered content, in five requests — then one write. Everything below is curl; the shapes are the same from any HTTP client. Replace YOUR_ORG_ID and atk_YOUR_TOKEN with the values from Studio → Settings → API tokens.

export HV_API=https://api.hypervalent.io/v1/orgs/YOUR_ORG_ID
export HV_AUTH="Authorization: Bearer atk_YOUR_TOKEN"

1. Check the token

curl -s "$HV_API/token" -H "$HV_AUTH"

The answer says whether the token is narrowed to a project (token.projectSlug) and whether it may write (features.apiTokensWrite). A 401 here means the token is wrong — see Errors.

2. Find the project

curl -s "$HV_API/projects" -H "$HV_AUTH"

{ "results": [{ "uuid": "…", "slug": "marketing", "title": "Marketing site" }], "count": 1, "limit": 10, "offset": 0, "page": 1 }

Pick a slug; every content URL from here on includes it:

export HV_PROJECT="$HV_API/projects/marketing"

3. Read the content model

curl -s "$HV_PROJECT/doctypes" -H "$HV_AUTH"

Each document type lists its root-atom bindings by uuid. Resolve those to field definitions once, and you know the shape of every document of that type:

curl -s "$HV_PROJECT/atoms" -H "$HV_AUTH"

{
  "results": [
    { "uuid": "1b2c…", "slug": "hero-image", "title": "Hero image", "fieldType": "image", "multiple": false, "…": "…" },
    { "uuid": "9e8f…", "slug": "summary", "title": "Summary", "fieldType": "textarea", "multiple": false, "…": "…" }
  ],
  "count": 2
}

4. List the documents of a type

curl -s "$HV_PROJECT/doctypes/article/documents?limit=20&page=1" -H "$HV_AUTH"

{
  "documentType": { "uuid": "…", "slug": "article", "title": "Article", "titlePlural": "Articles", "icon": null },
  "documents": {
    "results": [
      {
        "uuid": "…", "slug": "hello-world", "title": "Hello, world", "status": "published",
        "datePublished": "2026-09-01T10:00:00.000Z",
        "content": [ { "…": "the body tree" } ],
        "rootAtoms": [
          { "uuid": "1b2c…", "value": ["7d3a…"], "locked": false, "required": true },
          { "uuid": "9e8f…", "value": "A short summary.", "locked": false, "required": false }
        ],
        "…": "…"
      }
    ],
    "count": 42, "limit": 20, "offset": 0, "page": 1
  },
  "referencedImages": [ { "uuid": "7d3a…", "cdnUrl": "https://…/hero.jpg", "width": 1600, "height": 900, "…": "…" } ],
  "referencedFiles": [ { "uuid": "4b1c…", "title": "Price list", "url": "https://…/original.pdf", "filename": "price-list.pdf", "mime": "application/pdf", "size": 48213 } ],
  "poweredBy": "Powered by Hypervalent"
}

documents.count is the total; page with page=2, page=3, … The image the hero field refers to is in referencedImages, and a file field's PDF or document — or a video field's uploaded video — is in referencedFiles — no second request.

5. Read one document

curl -s "$HV_PROJECT/doctypes/article/documents/hello-world" -H "$HV_AUTH"

The single read adds the document's taxonomy terms (grouped by taxonomy, each with its own content) and the full version envelope. Render version.content as the body and version.rootAtoms as the fields, resolving each uuid through the atoms you fetched in step 3.

Settings and design tokens

The same pattern serves site-wide values: GET …/settings (and …/settings/site-title for one value), GET …/design-tokens as JSON, or link …/design-tokens.css straight from a page.

6. Write something (read + write token)

Writes need a read_write token on a plan with API writes. Create a draft:

curl -s -X POST "$HV_PROJECT/doctypes/article/documents" \
  -H "$HV_AUTH" -H "Content-Type: application/json" \
  -d '{
    "title": "Hello from the API",
    "rootAtoms": { "9e8f…": "Created with one request." }
  }'

• slug is derived from the title when omitted (hello-from-the-api, then -2, -3 on a collision).
• rootAtoms is keyed by atom uuid — the uuid of each entry in the document type's atoms. An unknown key is refused with 422 VALIDATION_ERROR naming the allowed list; nothing is written.
• The answer is the document's working view — the same body GET …/documents/hello-from-the-api?status=draft serves.

Then publish it — this makes it visible on the read API, and so on your site, at once:

curl -s -X POST "$HV_PROJECT/doctypes/article/documents/hello-from-the-api/publish" -H "$HV_AUTH"

To attach an image, upload it first and put the returned uuid in an image root atom:

curl -s -X POST "$HV_PROJECT/media" -H "$HV_AUTH" \
  -F "file=@hero.jpg" -F "title=Hero" -F "alt=A sunrise over the bay"

Editor locks

If someone has the document open in Studio, an edit answers 409 VERSION_LOCKED with holder.name and expiresAt, and nothing is written. Retry after the lock lapses.

Next

• Endpoint reference — every route, its query parameters, body and answer shape.
• OpenAPI document — import it into Postman, Insomnia or Bruno, or generate a typed client.
• Errors — every code, and what to do about it.
• Prefer to let an assistant do the writing? The MCP server exposes the same API as tools.