---
title: "Find items by document"
method: POST
path: "/items/by-document"
tags: ["Items"]
---

# Find items by document

`POST /items/by-document`

Returns the ids of the items linked to a document whose contents are identical to the file you provide, limited to the items your service account can access. Matching is by file contents, not file name.

Send the file as multipart/form-data in the `file` field. The file is hashed (SHA-256) as it uploads and is not stored. The response includes that hash as `file_hash`. To fetch further pages without uploading the file again, call this endpoint with the `file_hash` query parameter and no request body. Send either `file` or `file_hash`, not both.

Results are ordered by item id and paged with an opaque `cursor`. Pass the `next_cursor` from one response as `cursor` on the next call until it is absent. If no accessible item is linked to the document, `item_ids` is an empty array.

Files up to 512 MB are accepted, and large uploads have up to 5 minutes to complete. Requests may be rate limited. When the limit is exceeded the API returns 429 with a `Retry-After` header giving the seconds to wait.

Requires an access token with the `items:read` scope.

## Query parameters

- `file_hash` string
- `limit` integer
- `cursor` string

## Response `200`

OK

- HandlersItemsByDocumentResponse
  - `file_hash` string — hex SHA-256 of the document; pass it as file_hash to fetch further pages without uploading again
  - `item_ids` string[] — ids of the linked items, ordered by id; empty if none are accessible to your service account
  - `next_cursor` string — pass as cursor to get the next page; absent on the last page

## Other responses

- `400` — Invalid cursor or file_hash, both file and file_hash sent, a body that is not multipart/form-data, or no file part provided
- `401` — Missing, malformed, expired or invalidated access token (for example after a scope was removed or the account was revoked). The response carries a WWW-Authenticate: Bearer challenge.
- `403` — The access token does not grant the items:read scope
- `413` — The file exceeds the 512 MB limit
- `429` — Rate limit exceeded; see the Retry-After header
- `500` — Unexpected error while listing items
- `503` — Temporarily unavailable; retry later

## Changes

- **2026-10-02** `9de8eb88444b` — 6 info
  - the endpoint scheme security `OAuth2` was added to the API
  - the endpoint scheme security `BearerAuth` was removed from the API
  - api tag `Items` added
  - api tag `items` removed
  - …2 more
- **2026-10-01** `2acb74b9d45c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/resourcly/apis/resourcly-api/changes/items/by-document/post.md)

---

[API](https://skmtc.dev/resourcly/apis/resourcly-api.md) · [All operations](https://skmtc.dev/resourcly/apis/resourcly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/resourcly/apis/resourcly-api/revisions/9de8eb88444b?raw)