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.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
type?stringOnly 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?stringOnly 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?stringOnly return items stamped with this source.
tier?stringOnly return items in this tier. Omit it or send all for both tiers.
"library""feed""all"filter?stringA 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?stringAn 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?stringField 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.
^(created_at|updated_at|occurred_at|last_activity_at|properties\.[a-z0-9_]+)$direction?stringSort direction. Defaults to desc.
"asc""desc"occurred_after?stringOnly return items whose own time (occurred_at, else created_at) is after this time. For the modification time, use updated_after.
1 <= lengthoccurred_before?stringOnly return items whose own time (occurred_at, else created_at) is before this time.
1 <= lengthupdated_after?stringOnly 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.
1 <= lengthupdated_before?stringOnly return items changed before this time. It doesn't change the ordering, so it works with any sort.
1 <= lengthlimit?integerThe maximum number of results to return. Up to 500; a larger value is read as 500.
1 <= value50cursor?stringThe next_cursor from the previous page. Leave it out to get the first page.
include?stringComma-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.
X-Marfa-Reach?stringThe 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.
^[0-9a-f]{64}$64 <= length <= 64Returns a page of items. With include=metadata, each entry holds the item and its metadata.
application/json- 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_aftercomes with a differentsortordirection,cursorcame from another ordering or listing, orX-Marfa-Reachcomes withoutinclude=metadata.unknown_type:typeis a concrete type that nothing registers.
application/json- 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- response
An error response.
error*What went wrong.
type_not_permitted: your credential reaches no type, ortypenames a type you can't read with none readable under it.edge_type_not_permitted: the filter has anedgeorbackrefterm for an edge type you can't read.forbidden:typenamessystem.connectionand you don't holdgrants.manage.details.required_scopenames it.
application/json- response
An error response.
error*What went wrong.
reach_changed: the reach in X-Marfa-Reach has changed. Rebuild the working copy.
application/json- 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- 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- 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- 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- 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- response
An error response.
error*What went wrong.
curl -X GET 'http://localhost:8600/items'{ "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}