Items

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.

GET
/items/{id}

Authorization

bearerAuth
headerAuthorizationBearer <token>

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

Path parameters

id*string

The ID of the item.

Query parameters

include?string

Comma-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?string

Read 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.

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 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
  1. 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?boolean

true 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?boolean

true 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?integer

How 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, or state is empty, names a state that doesn't exist, or puts any beside another state.
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.
application/json
  1. response

An error response.

error*

What went wrong.

  • item_not_found: no item has this ID, the item is in a state state leaves out (details.trashed is true for an item in the trash whose type you can read), or its type is one you can't read.
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/string'
About errors
{  "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": {}  }}