---
title: "Report headless sessions' content-free totals and state to Den's session index"
method: POST
path: "/v1/internal/headless/index"
tags: ["Internal"]
---

# Report headless sessions' content-free totals and state to Den's session index

`POST /v1/internal/headless/index`

## Request

- Base URL: `https://api.openworklabs.com`
- URL: `https://api.openworklabs.com/v1/internal/headless/index`
- Auth: HTTP bearer

For the headless runner only, with `Authorization: Bearer $DEN_HEADLESS_RUNNER_CALLBACK_TOKEN`. Body `{ updates: [{ capability, sessionId, version, fields }] }`, at most 50. Each update carries the index capability Den minted with the session's turn; the organization, member and kind come from it alone and `sessionId` must be its session. Idempotent on (sessionId, version): a version at or below the stored one is `stale` and changes nothing. One result per update, in order: `ok`, `stale`, or `rejected` with a code (`rate_limited` per session and organization: keep and retry it; `index_disabled` is no longer sent but older runners keep and retry it too). Rejections are audited. Answers 404 when DEN_HEADLESS_RUNNER_CALLBACK_TOKEN is not configured.

## Response `200`

One result per update.

- object
  - `results` object[], required
    - `sessionId` string, required
    - `version` integer, required
    - `status` 'ok' | 'stale' | 'rejected', required
    - `error` 'invalid_update' | 'capability_invalid' | 'capability_expired' | 'capability_mismatch' | 'index_disabled' | 'rate_limited' | 'session_conflict'

## Other responses

- `400`: The body is not `{ updates: [...] }` with 1 to 50 updates.
- `401`: Missing or wrong callback token.
- `404`: Runner callbacks are not configured on this deployment.
- `500`: The index could not be written; retry with backoff.

## Changes

- **2026-10-20** `aef4d1db5034`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/internal/headless/index/post.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) · [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/e6eb4e5ce8a3?raw)