Get an item
Returns an item with its metadata and outbound edges. Use include to add its inbound edges, the items at the other end of its edges, or its version history in the same call. Use state to read an item in the trash.
bearerAuthAuthorizationBearer <token>Authenticate with an API key (marfa_k1_…) or an OAuth access token (marfa_at_…).
id*stringThe ID of the item.
include?stringComma-separated extras: backrefs adds inbound edges, neighbors adds the items at the other end of the edges returned, and versions adds the first page of version snapshots you can read, oldest first.
state?stringRead the item only if it is in one of these lifecycle states: one state or a comma-separated list, such as active,trashed. Send any on its own for every state, the trash included. Without it, you get an item in any state but trashed.
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 the item and its metadata, plus any extras you asked for. If neighbors hits its cap of 100 items, neighbors_truncated is true; neighbors_omitted counts neighbors you can't read.
application/json- response
An item as GET /items/{id} returns it: the item, its metadata, and the extras include asks for.
item*The item, with its outbound edges.
metadata*The item's metadata.
backrefs?The item's inbound edges you can read, by edge type. Each holds the first page of that type, which GET /items/{id}/backrefs continues. An edge whose from item source_filter leaves out doesn't appear. Present with include=backrefs.
listed?booleantrue if listings show you this item, false if source_filter leaves it out of them and you can read it only by ID. Present only when you send X-Marfa-Reach.
neighbors?array<>The items you can read at the far end of item.edges, and of backrefs if you asked for both, with their metadata. Leaves out system.* items without counting them in neighbors_omitted. Present with include=neighbors.
neighbors_truncated?booleantrue if this answer's edges reach more than 100 items, so neighbors leaves some out. Page GET /items/{id}/edges and GET /items/{id}/backrefs for the rest. Present with include=neighbors.
neighbors_omitted?integerHow many neighbors neighbors leaves out because you can't read their type. Present with include=neighbors.
versions?The first page of the item's version snapshots you can read, oldest first, which GET /items/{id}/versions continues. Present with include=versions.
invalid_id: the ID is not a valid item ID.validation_error: the query has a parameter this endpoint doesn't take, orstateis empty, names a state that doesn't exist, or putsanybeside another state.
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.
application/json- response
An error response.
error*What went wrong.
item_not_found: no item has this ID, the item is in a statestateleaves out (details.trashedistruefor an item in the trash whose type you can read), or its type is one you can't read.
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/string'{ "item": { "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": {} }, "metadata": { "item_id": "01a1011a-4902-76cf-a4a9-88e99c038c8d", "tags": [ "renewal" ], "extensions": {} }}