API reference / Space guide

Projects, folders and databases

Space is in development. These guides describe the current development version and the intended workflow. Public sign-ups and hosted agent connections are not available yet.

Workspace items and records.

Send every request to your API URL with your key, as described in the reference overview. Read API concepts for paging, safe retries, revisions and errors.

GET `/v1/spaces/{space_id}/items`

List workspace items of one kind

Sections, projects, folders, categories or databases of one kind. Pass deleted=true to list deleted ones.

Path parameters

space_idstring (uuid)Required

Query parameters

kindstringRequired
One of project, database, category, section, folder
afterstring (uuid) or null
deletedboolean
Default false

Responses

200Success

itemsarray of objectRequired
15 fields in items
- idstring (uuid)Required
- kindstringRequired
  One of section, project, folder, category, database
- revisionintegerRequired
- deletedbooleanRequired
- updated_atstring (date-time)Required
- author_agentobject or nullRequired
  5 fields in author_agent
  - idstring (uuid)Required
  - revisionintegerRequired
  - namestringRequired
  - harnessstringRequired
    The agent's software, such as claude, codex or cursor.
  - {key}any
    Any other key.
- namestringRequired
- descriptionstringRequired
- section_idstring (uuid) or null
  Projects: the parent section.
- project_idstring (uuid) or null
  Folders and databases.
- statusstring or null
  Projects: a task column value.
- fieldsarray of object or null
  Databases.
  4 fields in fields
  - idstringRequired
  - namestringRequired
  - typestringRequired
    text, number, select, checkbox, date and similar.
  - optionsarray of string
    Choices for select fields.
- recordsarray of object or null
  Databases.
  6 fields in records
  - idstringRequired
  - namestringRequired
  - notesstringRequired
  - createdAtstring (date-time) or null
  - updatedAtstring (date-time) or null
  - valuesobjectRequired
    Field values keyed by field id.
- viewstring or null
  Databases: table or board.
- groupBystring or null
  Databases: the board's field.
next_cursorstring (uuid) or nullRequired

Example response

{
  "items": [
    {
      "author_agent": null,
      "deleted": false,
      "description": "",
      "fields": [
        {
          "id": "company",
          "name": "Company",
          "options": [],
          "type": "text"
        },
        {
          "id": "value",
          "name": "Value",
          "options": [],
          "type": "number"
        }
      ],
      "groupBy": null,
      "id": "9d3b1d63-258d-4a4f-9e9e-6785d3c9a048",
      "kind": "database",
      "name": "Leads",
      "records": [
        {
          "createdAt": null,
          "id": "r1",
          "name": "Acme",
          "notes": "",
          "updatedAt": "2026-10-08T01:56:07.240528Z",
          "values": {
            "company": "Acme Ltd",
            "value": 150
          }
        }
      ],
      "revision": 2,
      "updated_at": "2026-10-08T01:56:07.242500+00:00",
      "view": "table"
    }
  ],
  "next_cursor": null
}

Errors

401The API key is missing, unknown, expired or revoked. Error
403Not allowed: a read-only key, a view-only role, or an operation keys cannot do. Error
404Not found. Other Spaces also look absent to a key. Error
422Invalid fields, revision or payload. Error
503Temporarily unavailable or busy. Retry with backoff, honouring Retry-After. Error

Example request

curl "https://<api-host>/v1/spaces/{space_id}/items?kind=project" \
  -H "Authorization: Bearer $SPACE_API_KEY"

POST `/v1/spaces/{space_id}/items`

Create or update a workspace item

Creates an item with a new item_id and expected_revision: 0, or replaces its data at the current revision. data depends on kind; databases carry fields and records.

Path parameters

space_idstring (uuid)Required

Request bodyRequired

command_idstring (uuid)Required
item_idstring (uuid)Required
expected_revisionintegerRequired
At least 0
kindstringRequired
One of project, database, category, section, folder
dataobjectRequired

Responses

200Success

idstring (uuid)Required
kindstringRequired
One of section, project, folder, category, database
revisionintegerRequired
deletedbooleanRequired
updated_atstring (date-time)Required
author_agentobject or nullRequired
5 fields in author_agent
- idstring (uuid)Required
- revisionintegerRequired
- namestringRequired
- harnessstringRequired
  The agent's software, such as claude, codex or cursor.
- {key}any
  Any other key.
namestringRequired
descriptionstringRequired
section_idstring (uuid) or null
Projects: the parent section.
project_idstring (uuid) or null
Folders and databases.
statusstring or null
Projects: a task column value.
fieldsarray of object or null
Databases.
4 fields in fields
- idstringRequired
- namestringRequired
- typestringRequired
  text, number, select, checkbox, date and similar.
- optionsarray of string
  Choices for select fields.
recordsarray of object or null
Databases.
6 fields in records
- idstringRequired
- namestringRequired
- notesstringRequired
- createdAtstring (date-time) or null
- updatedAtstring (date-time) or null
- valuesobjectRequired
  Field values keyed by field id.
viewstring or null
Databases: table or board.
groupBystring or null
Databases: the board's field.

Example response

{
  "author_agent": null,
  "deleted": false,
  "description": "",
  "id": "5c81be14-1e68-42d2-a4d4-48b684198713",
  "kind": "project",
  "name": "Beacon",
  "revision": 1,
  "section_id": "fde5224d-38ab-4b85-8cff-44f268d8b48b",
  "status": "todo",
  "updated_at": "2026-10-08T01:56:07.806410+00:00"
}

Errors

401The API key is missing, unknown, expired or revoked. Error
402An active subscription is required to add content. Reading, export and deletion still work. Error
403Not allowed: a read-only key, a view-only role, or an operation keys cannot do. Error
404Not found. Other Spaces also look absent to a key. Error
409Conflict: a stale expected_revision, a reused command_id, or a changed snapshot. Re-read and retry. Error
422Invalid fields, revision or payload. Error
429A Space quota is exhausted (storage, items or monthly model requests). Error
503Temporarily unavailable or busy. Retry with backoff, honouring Retry-After. Error

Example request

curl -X POST "https://<api-host>/v1/spaces/{space_id}/items" \
  -H "Authorization: Bearer $SPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command_id": "1fc6756b-2ec5-4338-b2d7-1cd961210e5c",
    "data": {
      "name": "Beacon",
      "section_id": "fde5224d-38ab-4b85-8cff-44f268d8b48b"
    },
    "expected_revision": 0,
    "item_id": "5c81be14-1e68-42d2-a4d4-48b684198713",
    "kind": "project"
  }'

GET `/v1/spaces/{space_id}/items/{item_id}`

Get a workspace item

One item. Pass revision to read an earlier revision.

Path parameters

space_idstring (uuid)Required
item_idstring (uuid)Required

Query parameters

revisioninteger or null

Responses

200Success

idstring (uuid)Required
kindstringRequired
One of section, project, folder, category, database
revisionintegerRequired
deletedbooleanRequired
updated_atstring (date-time)Required
author_agentobject or nullRequired
5 fields in author_agent
- idstring (uuid)Required
- revisionintegerRequired
- namestringRequired
- harnessstringRequired
  The agent's software, such as claude, codex or cursor.
- {key}any
  Any other key.
namestringRequired
descriptionstringRequired
section_idstring (uuid) or null
Projects: the parent section.
project_idstring (uuid) or null
Folders and databases.
statusstring or null
Projects: a task column value.
fieldsarray of object or null
Databases.
4 fields in fields
- idstringRequired
- namestringRequired
- typestringRequired
  text, number, select, checkbox, date and similar.
- optionsarray of string
  Choices for select fields.
recordsarray of object or null
Databases.
6 fields in records
- idstringRequired
- namestringRequired
- notesstringRequired
- createdAtstring (date-time) or null
- updatedAtstring (date-time) or null
- valuesobjectRequired
  Field values keyed by field id.
viewstring or null
Databases: table or board.
groupBystring or null
Databases: the board's field.

Example response

{
  "author_agent": null,
  "deleted": false,
  "description": "The Atlas launch.",
  "id": "fc2108b2-a7c2-43b4-b0ea-44c6e01a30a8",
  "kind": "project",
  "name": "Atlas",
  "revision": 1,
  "section_id": null,
  "status": "todo",
  "updated_at": "2026-10-08T01:56:07.179434+00:00"
}

Errors

401The API key is missing, unknown, expired or revoked. Error
403Not allowed: a read-only key, a view-only role, or an operation keys cannot do. Error
404Not found. Other Spaces also look absent to a key. Error
422Invalid fields, revision or payload. Error
503Temporarily unavailable or busy. Retry with backoff, honouring Retry-After. Error

Example request

curl "https://<api-host>/v1/spaces/{space_id}/items/{item_id}" \
  -H "Authorization: Bearer $SPACE_API_KEY"

POST `/v1/spaces/{space_id}/databases/{database_id}/query`

Query a database

Runs SQLite-dialect SQL against one database's records table. Reads need nothing else; writes (INSERT, UPDATE, DELETE) need a read-write key plus command_id and the database's current expected_revision. include_schema=true maps field names to SQL columns.

Path parameters

space_idstring (uuid)Required
database_idstring (uuid)Required

Request bodyRequired

sqlstring or null
1 to 10000 characters
paramsarray of (string or integer or number or boolean or null)
Up to 100 items
statementsarray of object or null
1 to 20 items
2 fields in statements
- sqlstringRequired
  1 to 10000 characters
- paramsarray of (string or integer or number or boolean or null)
  Up to 100 items
command_idstring (uuid) or null
expected_revisioninteger or null
At least 1
max_rowsinteger
1 to 500Default 100
include_schemaboolean
Default false

Responses

200Success

databaseobjectRequired
2 fields in database
- idstring (uuid)Required
- revisionintegerRequired
resultsarray of objectRequired
One result per statement.
4 fields in results
- columnsarray of stringRequired
- rowsarray of array of anyRequired
- row_countintegerRequired
- truncatedbooleanRequired
  True when more rows matched than max_rows.
changesobject or nullRequired
Row counts for a write; null for a read.
3 fields in changes
- insertedintegerRequired
- updatedintegerRequired
- deletedintegerRequired
schemaarray of object or null
With include_schema=true.
4 fields in schema
- columnstringRequired
  The SQL column name to use in queries.
- field_idstringRequired
- typestringRequired
- optionsarray of stringRequired

Example response

{
  "changes": {
    "deleted": 0,
    "inserted": 0,
    "updated": 1
  },
  "database": {
    "id": "9d3b1d63-258d-4a4f-9e9e-6785d3c9a048",
    "revision": 2
  },
  "results": [
    {
      "columns": [],
      "row_count": 0,
      "rows": [],
      "truncated": false
    }
  ]
}

Errors

401The API key is missing, unknown, expired or revoked. Error
402An active subscription is required to add content. Reading, export and deletion still work. Error
403Not allowed: a read-only key, a view-only role, or an operation keys cannot do. Error
404Not found. Other Spaces also look absent to a key. Error
409Conflict: a stale expected_revision, a reused command_id, or a changed snapshot. Re-read and retry. Error
422Invalid fields, revision or payload. Error
429A Space quota is exhausted (storage, items or monthly model requests). Error
503Temporarily unavailable or busy. Retry with backoff, honouring Retry-After. Error

Example request

curl -X POST "https://<api-host>/v1/spaces/{space_id}/databases/{database_id}/query" \
  -H "Authorization: Bearer $SPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "command_id": "3310a5f2-58cd-4000-be97-fac341535d27",
    "expected_revision": 1,
    "params": [
      150,
      "Acme"
    ],
    "sql": "UPDATE records SET Value = ? WHERE name = ?"
  }'

Articles Discover Space Memory questions

Projects, folders and databases

GET /v1/spaces/{space_id}/items

Path parameters

Query parameters

Responses

Example request

POST /v1/spaces/{space_id}/items

Path parameters

Request bodyRequired

Responses

Example request

GET /v1/spaces/{space_id}/items/{item_id}

Path parameters

Query parameters

Responses

Example request

POST /v1/spaces/{space_id}/databases/{database_id}/query

Path parameters

Request bodyRequired

Responses

Example request

GET `/v1/spaces/{space_id}/items`

POST `/v1/spaces/{space_id}/items`

GET `/v1/spaces/{space_id}/items/{item_id}`

POST `/v1/spaces/{space_id}/databases/{database_id}/query`