Datalumo
Docs · Pages API
View markdown

Pages API

Organisation API for listing, pushing, and deleting pages on a source. Create an API source first. WordPress, Shopify, Laravel, and the PHP client use these endpoints under the hood.

Push, list, and delete pages on a source. After you push content, Datalumo indexes it in the background. Successful writes return 202 and the page stays in pending until indexing finishes.

You can identify a source by slug or public id.

Base path: /api/v1/{organisation}/sources/{source}/pages

#List pages

GET /sources/{source}/pages

Permission: pages.read

#Query parameters

Param Type Default Description
external_id string Only this external id
status string Filter by status, e.g. pending, indexed, failed
cursor string Cursor from a previous response
per_page int 25 Page size, 1-100

#Response

Results are cursor-paginated:

{
  "data": [
    {
      "id": "0194b…",
      "external_id": "wp-42",
      "name": "Hello world",
      "source_type": "api_push",
      "source_url": "https://example.com/hello-world",
      "thumbnail": "https://example.com/hello-world.jpg",
      "status": "indexed",
      "excluded": false,
      "error": null,
      "size_bytes": 1234,
      "meta": { "author": "Jane" },
      "created_at": "2026-07-01T12:00:00+00:00",
      "updated_at": "2026-07-01T12:01:00+00:00"
    }
  ],
  "links": { "first": "…", "last": null, "prev": null, "next": "…" },
  "meta": { "path": "…", "per_page": 25, "next_cursor": "…", "prev_cursor": null }
}

#Create or update a page

POST /sources/{source}/pages

Permission: pages.write
Status: 202 Accepted

If you send the same external_id again, Datalumo updates that page and re-indexes it. Sending the exact same content for a page that is already indexed does nothing.

#Body

Field Type Required Description
content string yes Full page body
external_id string no Stable id from your system (post id, path, and so on). Recommended so updates replace the right page.
name string no Display title
content_mime string no Defaults to text/plain. Supported: text/plain, text/markdown, text/html. Prefer HTML or Markdown for pushed content. Markdown may include YAML frontmatter (title becomes the page name; draft / hidden skip indexing).
source_url string no Public URL used in citations
thumbnail string or null no Public image URL. The search widget shows it when Thumbnails is on under Look. Omit the field to leave a stored URL. Send null to clear it.
meta object no Extra JSON metadata stored with the page

#Example

curl -sS -X POST \
  -H "Authorization: Bearer $DATALUMO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "wp-42",
    "name": "Hello world",
    "content": "# Hello world\n\nBody…",
    "content_mime": "text/markdown",
    "source_url": "https://example.com/hello-world",
    "thumbnail": "https://example.com/hello-world.jpg",
    "meta": { "author": "Jane" }
  }' \
  "https://datalumo.app/api/v1/{organisation}/sources/docs/pages"

#Response

{
  "data": {
    "id": "0194b…",
    "external_id": "wp-42",
    "name": "Hello world",
    "source_type": "api_push",
    "status": "pending",
    "…"
  }
}

If your plan's page limit is full, the request is rejected before the page is created.

#Batch create or update

POST /sources/{source}/pages/batch

Permission: pages.write
Status: 202 Accepted
Limit: 1-50 pages per request

#Body

{
  "pages": [
    {
      "external_id": "wp-42",
      "content": "…",
      "content_mime": "text/markdown"
    },
    {
      "external_id": "wp-43",
      "content": "…"
    }
  ]
}

Each item uses the same fields as the single-page endpoint. The response is a list of page objects.

#Delete a page

DELETE /sources/{source}/pages/{page}

Permission: pages.write
Status: 204 No Content

{page} can be:

  • the page's public id (UUID), or
  • the external_id you sent when you pushed it

Unknown ids return 404.