Items

List items

Returns a page of the items you can read that match the filters. System items are left out unless you ask for them with include=system. Use include to add edges, metadata or extensions to each item.

GET
/items

Authorization

bearerAuth
headerAuthorizationBearer <token>

Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).

Query parameters

type?string

Only return items of these types and their subtypes: a comma-separated list of up to 10, such as core.note,app.*. A wildcard such as core.* matches every type under that prefix.

state?string

Only return items in these lifecycle states: one state or a comma-separated list, such as active,archived. Without it, you get active items. Send any on its own to get every state.

source?string

Only return items stamped with this source.

tier?string

Only return items in this tier. Omit it or send all for both tiers.

Value in"library""feed""all"
tags?string

Comma-separated tags. Only return items that carry all of them. At most 100 distinct tags, each at most 128 characters.

filter?string

A filter expression. A term naming an edge type, edge[<type>] or backref[<type>], needs read on it; edge[<type>]=<id> also works as a query parameter. status_group matches by status group; properties.<field>.<member>, by a list entry.

beneath?string

An item ID. Only return that item and the items under it by parent-of edges, at any depth, walking only through items you can read. Needs read on parent-of edges.

sort?string

Field to sort by: created_at, updated_at, occurred_at, last_activity_at or properties.<field>. Properties sort by stored value: an enum sorts alphabetically. Defaults to created_at, or the trash time for state=trashed alone.

Match^(created_at|updated_at|occurred_at|last_activity_at|properties\.[a-z0-9_]+)$
direction?string

Sort direction. Defaults to desc.

Value in"asc""desc"
occurred_after?string

Only return items whose own time (occurred_at, else created_at) is after this time. For the modification time, use updated_after.

Length1 <= length
occurred_before?string

Only return items whose own time (occurred_at, else created_at) is before this time.

Length1 <= length
updated_after?string

Only return items changed at or after this time. Send the latest updated_at you hold, and deduplicate by ID, as items can share an instant. Ordered by updated_at, then ID, ascending, so leave out sort and direction. Purges aren't reported.

Length1 <= length
updated_before?string

Only return items changed before this time. It doesn't change the ordering, so it works with any sort.

Length1 <= length
limit?integer

The maximum number of results to return. Up to 500; a larger value is read as 500.

Range1 <= value
Default50
cursor?string

The next_cursor from the previous page. Leave it out to get the first page.

include?string

Comma-separated extras. edges, metadata and extensions add that data to each item. system also returns system.* items, which are left out by default; a system. type filter does the same.

Header parameters

X-Marfa-Reach?string

The reach from a copy stream, for a working copy. Marfa reads the current data and checks the reach in one snapshot, and returns 409 reach_changed if it has changed. Leave it out for an ordinary read.

Match^[0-9a-f]{64}$
Length64 <= length <= 64

Response body

About errors

Returns a page of items. With include=metadata, each entry holds the item and its metadata.

application/json
  1. response

A page of items.

data*array<|>

The items on this page.

next_cursor*|

Pass as cursor for the next page; null on the last. A page can be short, or empty, with a cursor still to follow, so a walk stops on null and never on a short page.

  • validation_error: a query parameter is unknown or invalid, updated_after comes with a different sort or direction, cursor came from another ordering or listing, or X-Marfa-Reach comes without include=metadata.
  • unknown_type: type is a concrete type that nothing registers.
application/json
  1. response

An error response.

error*

What went wrong.

unauthorized: the request has no credential, or its credential is not valid. For a key that has expired, details.expired_at says when it expired.

application/json
  1. response

An error response.

error*

What went wrong.

  • type_not_permitted: your credential reaches no type, or type names a type you can't read with none readable under it.
  • edge_type_not_permitted: the filter has an edge or backref term for an edge type you can't read.
  • forbidden: type names system.connection and you don't hold grants.manage. details.required_scope names it.
application/json
  1. response

An error response.

error*

What went wrong.

reach_changed: the reach in X-Marfa-Reach has changed. Rebuild the working copy.

application/json
  1. response

An error response.

error*

What went wrong.

contract_mismatch: X-Marfa-Contract names another contract version than this instance speaks, or is not a whole number. Nothing was done.

application/json
  1. response

An error response.

error*

What went wrong.

rate_limited: you sent too many requests. Wait for the number of seconds in Retry-After, then try again.

application/json
  1. response

An error response.

error*

What went wrong.

internal_error: Marfa failed in a way it didn't expect, and the request may not have completed. Read what you changed before you repeat a write.

application/json
  1. response

An error response.

error*

What went wrong.

write_contention: the database was busy, and Marfa couldn't complete the request in time. Nothing changed. Try the request again. While a restore runs, details.reason is restore_running.

application/json
  1. response

An error response.

error*

What went wrong.

insufficient_storage: the disk that holds the instance's data has no room for the request, or the request would leave less free than the instance keeps in reserve. Nothing changed, unless details.write_outcome is unknown, which means the write may have landed: read what you changed before you repeat it. Free space on the disk, then try the request again.

application/json
  1. response

An error response.

error*

What went wrong.

curl -X GET 'http://localhost:8600/items'
About errors
{  "data": [    {      "id": "01a10119-55c0-77ac-9589-f7c48fa642b6",      "type": "acme.deal",      "state": "active",      "tier": "library",      "created_at": "2026-10-03T09:38:25.218Z",      "updated_at": "2026-10-03T09:38:25.218Z",      "last_activity_at": "2026-10-03T09:38:25.218Z",      "occurred_at": "2026-10-03T09:38:25.218Z",      "source": "crm",      "source_id": "deal-1043",      "version": 1,      "schema_version": 1,      "trashed_at": null,      "read_only": false,      "properties": {        "name": "Pilot for Sample Ltd",        "amount": 4500,        "stage": "won"      },      "edges": {}    },    {      "id": "01a1011a-4902-76cf-a4a9-88e99c038c8d",      "type": "acme.deal",      "state": "active",      "tier": "library",      "created_at": "2026-10-03T09:37:25.975Z",      "updated_at": "2026-10-03T09:37:25.975Z",      "last_activity_at": "2026-10-03T09:37:25.975Z",      "occurred_at": "2026-10-03T09:37:25.975Z",      "source": "crm",      "source_id": "deal-1042",      "version": 1,      "schema_version": 1,      "trashed_at": null,      "read_only": false,      "properties": {        "name": "Renewal for Example Co",        "amount": 12000,        "stage": "lead"      },      "edges": {}    }  ],  "next_cursor": null}