06 api reference

Data store API

The data store API lives under /api/data and exposes the structured entries agents save while working — read them, list attached files, download content, roll back versions, or enforce retention cleanup.

Authentication

Viewer role or above for reads, Editor or above for retention policy changes and deletes. See API overview for auth details.

Entries and files

Most of the data store is organised by entries — structured JSON records scoped to a project. Each entry can have files attached (binary content, images, PDFs, etc.) and is versioned (every save creates a new version).

`GET /api/data/{entryId}/files`

List all files attached to a specific data entry.

Response: an array of file metadata objects with id, name, size, mime type, and timestamps.

`POST /api/data/{entryId}/files`

Upload a file and attach it to an entry. Expects a multipart/form-data request.

curl -X POST https://your-exolvra.example/api/data/entry_abc/files \
  -H "Authorization: Bearer exou_..." \
  -F "file=@./findings.pdf"

Response: the new file metadata object.

`GET /api/data/files/{fileId}`

Get metadata for a specific file without downloading its content.

Response: file metadata object.

`GET /api/data/files/{fileId}/content`

Download the raw content of a file. Returns the bytes with the appropriate Content-Type header.

curl https://your-exolvra.example/api/data/files/file_xyz/content \
  -H "Authorization: Bearer exou_..." \
  -o findings.pdf

`DELETE /api/data/files/{fileId}`

Delete a single file. The parent entry is not affected — other files stay attached.

Response: 204 No Content.

Versioning

Every data entry has a version history. Each time an agent updates the entry, a new version is created with an incrementing version number.

`GET /api/data/{entryId}/versions`

List versions for a data entry, newest first.

Query parameters:

Parameter	Type	Description
`max`	int	Limit the number of versions returned (default unlimited)

Response: an array of version metadata objects with version number, author agent, timestamp, and a short summary of what changed.

`GET /api/data/{entryId}/versions/{versionNumber}`

Get a specific version of an entry. Useful for diffing or restoring.

Response: the full entry content as it existed at that version number.

`POST /api/data/{entryId}/versions/{versionNumber}/restore`

Restore an entry to a previous version. This creates a new version with the old content — it doesn’t rewrite history. The version you’re restoring from is preserved.

Response: the new version object.

Retention

The data store supports per-project retention policies. Entries older than the retention window are automatically purged.

`GET /api/data/retention/{projectName}`

Get the retention policy for a project.

Response:

{
  "projectName": "q2-launch",
  "maxAgeDays": 90,
  "enabled": true
}

`PUT /api/data/retention/{projectName}`

Set or update the retention policy for a project.

Request body:

{
  "maxAgeDays": 90,
  "enabled": true
}

Response: the updated policy object.

`POST /api/data/retention/enforce`

Manually trigger a retention sweep across all projects with active policies. Normally this runs on a schedule, but you can force it via API when needed.

Query parameters:

Parameter	Type	Description
`confirm`	bool	Must be `true` — destructive, runs immediately

Response: a summary of what was purged:

{
  "entriesDeleted": 42,
  "filesDeleted": 17,
  "bytesReclaimed": 5678901
}

Storage info

`GET /api/data/storage`

Get metadata about the storage backend currently in use (local disk, S3, Azure Blob) and total space used.

Response:

{
  "backend": "LocalDisk",
  "totalFiles": 1234,
  "totalBytes": 9876543210,
  "totalBytesReadable": "9.2 GB"
}

Useful for monitoring disk usage in self-hosted deployments.

Example — read an entry and download a file

# List files attached to entry_abc
curl https://your-exolvra.example/api/data/entry_abc/files \
  -H "Authorization: Bearer exou_..."

# Download one of them
curl https://your-exolvra.example/api/data/files/file_xyz/content \
  -H "Authorization: Bearer exou_..." \
  -o result.pdf

Where to go next

Data browser — the dashboard counterpart
Memory & knowledge — how the data store differs from memory
Projects API — data entries are scoped to projects