---
title: "Lookup Elements"
method: POST
path: "/v1/documents/{document_id}/elements/lookup"
tags: ["documents"]
---

# Lookup Elements

`POST /v1/documents/{document_id}/elements/lookup`

## Request

- Base URL: `https://api.versionstory.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.versionstory.com/v1/documents/{document_id}/elements/lookup`
- Auth: HTTP bearer

Find elements of one version of a document (paragraphs, tables, rows, cells) in its other versions, by id rather than
by text. Give the version ({"version_id": version_id}, or its reference as a response gave it) and ids, each the id
that version's listing prints for a paragraph, table, row or cell of its body (up to 1000). The answer gives each
element's type and its ids in every version (or the versions you list), following the map each version's redline
keeps, forward and back: one id, several where it was split, none where it was deleted or in a version made before it
was added. With formats (md, json) it also gives the element's content in each version where it has ids, as that
version's listing renders it, from its redline with its tracked changes (show_changes, the default; a first version
reads clean) or from its file. Use it to carry a reference to a clause, a table or a cell from one version to another,
or to read how it changed.

## Path parameters

- `document_id` string, required: The Document's document_id, a UUID.

## Headers

- `X-Customer-Id` string, nullable: Id of one of your customers (created in the developer dashboard) to attribute this request's credit usage to. Billing and limits stay organization-wide.

## Request body

- ElementLookupRequest: POST /v1/documents/{document_id}/elements/lookup's body.
  - `version` VersionLocator, required: A version: {"version_id": version_id}, or a version reference as a response gave it.
    - `version_id` string, required: The version's id, or "latest" for the newest.
    - `document_id` string, nullable: A reference's; must be the request's Document.
    - `index` integer, nullable: Ignored.
    - `label` string, nullable: Ignored.
  - `ids` string[], required: Ids of that version's body paragraphs, tables, rows and cells, as its listing prints them; each is answered once, in the order given.
  - `versions` VersionLocator[], nullable: The versions to answer for; every version by default.
    - `version_id` string, required: The version's id, or "latest" for the newest.
    - `document_id` string, nullable: A reference's; must be the request's Document.
    - `index` integer, nullable: Ignored.
    - `label` string, nullable: Ignored.
  - `formats` string[], nullable: The element's content in each version, as its listing renders it; ids alone without it.
  - `show_changes` boolean: Read the content from each version's redline, with its tracked changes (a first version has none, so it reads clean); false reads it from the version's file.

## Response `200`

Successful Response

- ElementLookupResponse
  - `elements` LookedUpElement[], required: One per requested element, in the order asked.
    - `id` string, required: The element's id in the version the request names.
    - `type` 'paragraph' | 'table' | 'row' | 'cell', required
    - `versions` ElementInVersion[], required: Every version asked for, in index order.
      - `version` VersionReference, required: A version a response points at: a parent, a Document's latest version, an edit's version. Sent back as it is, it names the version in a request (VersionLocator reads its version_id).
        - `document_id` string, required: The Document the version belongs to.
        - `version_id` string, required: The version's id.
        - `index` integer, required: The version's position among its Document's versions in the order they were made, counted from 0: the first version, v1, is index 0. It shows the order and names nothing: deleting a version moves the ones after it down, so a request names a version by its version_id.
        - `label` string, required: The app's label for the version, such as v2, or v2(a) for one of competing drafts, which the user names it by. It comes from the version graph, so a sibling added later can relabel it.
      - `ids` string[], required: The element's ids in this version: one, several when it was split, none when it was deleted (or, in an earlier version, when it was added after it).
      - `content` ElementContent
        - `md` string, nullable: The element's lines of the md listing.
        - `json` unknown[], nullable: The element's listing blocks: a paragraph's block, a table with its rows and cells, a row with its cells, or a cell with its blocks, each as its table's json holds it.
          - unknown

## Other responses

- `400`: The request is invalid: INVALID_REQUEST when a parameter or the body fails validation, otherwise the code of the operation's own refusal.

---

[API](https://skmtc.dev/versionstory/apis/version-story-public-api.md) - [All operations](https://skmtc.dev/versionstory/apis/version-story-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/versionstory/apis/version-story-public-api/revisions/994ce15faf32?raw)