API reference

Items

What is in a project's Data Management: pages, files, datasets, images and links. Read any item's details and a page's text, and create pages. Files can be listed and described but not uploaded or downloaded in v1.

List a project's items

The items in a project's Data Management, newest first, in every folder unless folder_id is given. Deleted items are left out. A list item carries no body: read a page with Get an item.

Parameters

Response 200

Errors

• 400 The request is not valid.
• 401 No valid API key.
• 403 The key may not do this.
• 404 Not found in this account.
• 429 Too many requests.
• 500 Something went wrong on our side.

The codes are listed under Errors.

curl "https://api.veragen.ai/v1/projects/{id}/items?limit=25" \
  -H "Authorization: Bearer $VERAGEN_API_KEY"

const res = await fetch("https://api.veragen.ai/v1/projects/{id}/items?limit=25", {
  headers: { Authorization: `Bearer ${process.env.VERAGEN_API_KEY}` },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.veragen.ai/v1/projects/{id}/items",
    params={"limit": 25},
    headers={"Authorization": f"Bearer {os.environ['VERAGEN_API_KEY']}"},
)
data = res.json()

{
  "data": [
    {
      "id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a",
      "project_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "folder_id": null,
      "name": "Competitor digest",
      "kind": "page",
      "ext": "html",
      "size_bytes": 1834,
      "status": "ready",
      "grounding": true,
      "created_at": "2026-10-03T06:01:12.000Z",
      "updated_at": "2026-10-03T06:01:12.000Z"
    },
    {
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
      "project_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "folder_id": "8f7e6d5c-4b3a-4c2d-9e1f-0a9b8c7d6e5f",
      "name": "Pricing survey.pdf",
      "kind": "file",
      "ext": "pdf",
      "size_bytes": 482113,
      "status": "ready",
      "grounding": true,
      "created_at": "2026-09-20T11:00:00.000Z",
      "updated_at": "2026-09-20T11:02:40.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a page

Creates a page in the project's Data Management, at the top of the project or in folder_id, and answers 201 with it. Send the text as Markdown or HTML. It is cleaned exactly as a page saved in the hub is: scripts, event handlers, styles and anything else a page cannot hold are removed, so what you read back can differ from what you sent. Markdown is stored as HTML, so the page reads back with format: "html". The page has a first version in its history, and is searched by Chat & Research and Odin like any other page once it has been indexed, which is billed as indexing any page is.

Idempotency-Key is optional here and recommended: a retry with the same key and the same request returns the first answer, with Idempotent-Replay: true, and never makes a second page. Files cannot be uploaded in v1.

Parameters

Response 201

Errors

• 400 The request is not valid.
• 401 No valid API key.
• 403 The key may not do this.
• 404 Not found in this account.
• 409 The Idempotency-Key is busy, or its first request did not finish.
• 413 The page is too large.
• 422 A body field cannot be used.
• 429 Too many requests.
• 500 Something went wrong on our side.

The codes are listed under Errors.

curl -X POST "https://api.veragen.ai/v1/projects/{id}/items" \
  -H "Authorization: Bearer $VERAGEN_API_KEY" \
  -H "Idempotency-Key: 6f1d2c3b-page-2026-10-03-1420" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 board summary", "format": "markdown", "content": "# Q3 board summary\n\nRevenue grew **12%** on Q2.", "folder_id": null}'

const res = await fetch("https://api.veragen.ai/v1/projects/{id}/items", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VERAGEN_API_KEY}`, "Idempotency-Key": "6f1d2c3b-page-2026-10-03-1420", "Content-Type": "application/json" },
  body: JSON.stringify({
    "name": "Q3 board summary",
    "format": "markdown",
    "content": "# Q3 board summary\n\nRevenue grew **12%** on Q2.",
    "folder_id": null
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.veragen.ai/v1/projects/{id}/items",
    headers={"Authorization": f"Bearer {os.environ['VERAGEN_API_KEY']}", "Idempotency-Key": "6f1d2c3b-page-2026-10-03-1420"},
    json={
        "name": "Q3 board summary",
        "format": "markdown",
        "content": "# Q3 board summary\n\nRevenue grew **12%** on Q2.",
        "folder_id": None
    },
)
data = res.json()

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a",
  "project_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "folder_id": null,
  "name": "Q3 board summary",
  "kind": "page",
  "ext": "html",
  "size_bytes": 72,
  "status": "ready",
  "grounding": true,
  "created_at": "2026-10-03T06:01:12.000Z",
  "updated_at": "2026-10-03T06:01:12.000Z",
  "body": {
    "format": "html",
    "content": "<h1>Q3 board summary</h1>\n<p>Revenue grew <strong>12%</strong> on Q2.</p>\n"
  }
}

Get an item

One item. For a page, body holds its text, as HTML (or Markdown, for a page that was stored as Markdown); images in a page are references (<img data-vg-item="…">), not links. For a file, dataset, image or link, body is null in v1.

Parameters

Response 200

Errors

• 400 The request is not valid.
• 401 No valid API key.
• 403 The key may not do this.
• 404 Not found in this account.
• 429 Too many requests.
• 500 Something went wrong on our side.

The codes are listed under Errors.

curl "https://api.veragen.ai/v1/items/{id}" \
  -H "Authorization: Bearer $VERAGEN_API_KEY"

const res = await fetch("https://api.veragen.ai/v1/items/{id}", {
  headers: { Authorization: `Bearer ${process.env.VERAGEN_API_KEY}` },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.veragen.ai/v1/items/{id}",
    headers={"Authorization": f"Bearer {os.environ['VERAGEN_API_KEY']}"},
)
data = res.json()

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6e5f4d3c2b1a",
  "project_id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "folder_id": null,
  "name": "Competitor digest",
  "kind": "page",
  "ext": "html",
  "size_bytes": 1834,
  "status": "ready",
  "grounding": true,
  "created_at": "2026-10-03T06:01:12.000Z",
  "updated_at": "2026-10-03T06:01:12.000Z",
  "body": {
    "format": "html",
    "content": "<h1>Competitor digest</h1>\n<p>Three launches this week.</p>\n"
  }
}