---
title: "Grid operations"
method: POST
path: "/api/v1/annotations/{annotationID}/content/{multivalueID}/grid_operations"
tags: ["Annotation Content"]
---

# Grid operations

`POST /api/v1/annotations/{annotationID}/content/{multivalueID}/grid_operations`

This endpoint applies multiple operations on multiple grids for one multivalue and performs OCR if required,
and updates the multivalue with the resulting grid.

For `update` operation the position of the grid and its rows and columns can be changed, the column layout
can be changed, but the row structure must be unchanged.

The operations are applied sequentially. The `grid_index` corresponds to the index of the grid parts when
the operation is applied. Combining different types of operations is not supported.

## Path parameters

- `annotationID` integer, required
- `multivalueID` integer, required

## Request body

- GridOperationsRequest — Request to apply multiple operations on multiple grids for one multivalue
  - `operations` object[], required — List of operations to apply to the grid
    - `op` 'update' | 'delete' | 'create', required — Type of operation
    - `grid_index` integer, required — Index of the grid
    - `grid` GridPart — A single grid part representing table structure on a page
      - `page` integer, required — Page number
      - `columns` object[], required — Description of grid columns
        - `left_position` number, required — Position of the column left edge
        - `schema_id` string, required — Reference to datapoint schema id
        - `header_texts` string[] — Extracted texts from column headers
      - `rows` object[], required — Description of grid rows
        - `top_position` number, required — Position of the row top edge
        - `tuple_id` integer, nullable — ID of the corresponding tuple datapoint if it exists else null
        - `type` string, nullable — Row type. If null, the row is ignored during grid-to-table conversion
        - `tuple_index` integer — Index for tuple_id re-mapping after creation of a new row (internal use)
      - `width` number — Total width of the grid
      - `height` number — Total height of the grid

## Response `200`

OK - Returns updated multivalue content as a tree, with only updated datapoints

- AnnotationContentMultivalue — A container for a list of datapoints or tuples, used to represent recurring items or table rows.
  - `id` integer, required — A unique ID of a given object.
  - `url` string, uri, required — URL of a given object.
  - `schema_id` string, required — Reference mapping the object to the schema tree.
  - `category` 'multivalue', required — Type of the object.
  - `hidden` boolean — If set to true, the datapoint is not visible in the user interface, but remains stored in the database.
  - `children` union[], required
    - union — Represents a datapoint or tuple object within the multivalue context.
      - object — A container for a set of related datapoints, representing a table row. Must be nested within a multivalue.
        - `id` integer, required — A unique ID of a given object.
        - `url` string, uri, required — URL of a given object.
        - `schema_id` string, required — Reference mapping the object to the schema tree.
        - `category` 'tuple', required — Type of the object.
        - `hidden` boolean — If set to true, the datapoint is not visible in the user interface, but remains stored in the database.
        - `children` AnnotationContentDatapoint[], required
          - `id` integer, required — A unique ID of a given object.
          - `url` string, uri, required — URL of a given object.
          - `schema_id` string, required — Reference mapping the object to the schema tree.
          - `category` 'datapoint', required — Type of the object.
          - `hidden` boolean — If set to true, the datapoint is not visible in the user interface, but remains stored in the database.
          - `content` AnnotationContentDatapointContent, required — A dictionary of the writable attributes of a given datapoint. Can be null for datapoints of type `button`.
            - `value` string — The extracted data of a given node. Maximum length: 1500 UTF characters.
            - `normalized_value` string, nullable — Normalized value for date (in ISO 8601 format) and number fields (in JSON number format).
            - `page` integer, nullable — Number of page where the data is situated (see position).
            - `position` number[], nullable — List of the coordinates of the label box of the given node. (left, top, right, bottom)
            - `rir_text` string, nullable — The extracted text, used as a reference for data extraction models.
            - `rir_raw_text` string, nullable — Raw extracted text (only for internal purposes, may be removed in the future).
            - `rir_page` integer, nullable — The extracted page, used as a reference for data extraction models.
            - `rir_position` number[], nullable — The extracted position, used as a reference for data extraction models. (left, top, right, bottom)
            - `rir_confidence` number, float, nullable — Confidence (estimated probability) that this field was extracted correctly.
            - `connector_text` string, nullable — Text set by the connector.
            - `connector_position` number[], nullable — Position set by the connector. (left, top, right, bottom)
            - `ocr_text` string, nullable — Value extracted by OCR, if applicable. (only for internal purposes, may be removed in the future)
            - `ocr_raw_text` string, nullable — Raw value extracted by OCR, if applicable. (only for internal purposes, may be removed in the future)
            - `ocr_position` number[], nullable — OCR position, if applicable. (left, top, right, bottom) (only for internal purposes, may be removed in the future)
          - `validation_sources` ValidationSource[], required — See [Validation Source](#validation-source) for details.
          - `time_spent` number, float, required — Time spent while actively working on a given node, in seconds.
          - `time_spent_overall` number, float, required — Total time spent while validating a given node, in seconds. Only for internal purposes.
          - `no_recalculation` boolean — If set to true, the datapoint's formula is not recalculated automatically. Only available for datapoint category editable formula datapoints.
      - object — A datapoint with a single value.
        - `id` integer, required — A unique ID of a given object.
        - `url` string, uri, required — URL of a given object.
        - `schema_id` string, required — Reference mapping the object to the schema tree.
        - `category` 'datapoint', required — Type of the object.
        - `hidden` boolean — If set to true, the datapoint is not visible in the user interface, but remains stored in the database.
        - `content` AnnotationContentDatapointContent, required — A dictionary of the writable attributes of a given datapoint. Can be null for datapoints of type `button`.
          - `value` string — The extracted data of a given node. Maximum length: 1500 UTF characters.
          - `normalized_value` string, nullable — Normalized value for date (in ISO 8601 format) and number fields (in JSON number format).
          - `page` integer, nullable — Number of page where the data is situated (see position).
          - `position` number[], nullable — List of the coordinates of the label box of the given node. (left, top, right, bottom)
          - `rir_text` string, nullable — The extracted text, used as a reference for data extraction models.
          - `rir_raw_text` string, nullable — Raw extracted text (only for internal purposes, may be removed in the future).
          - `rir_page` integer, nullable — The extracted page, used as a reference for data extraction models.
          - `rir_position` number[], nullable — The extracted position, used as a reference for data extraction models. (left, top, right, bottom)
          - `rir_confidence` number, float, nullable — Confidence (estimated probability) that this field was extracted correctly.
          - `connector_text` string, nullable — Text set by the connector.
          - `connector_position` number[], nullable — Position set by the connector. (left, top, right, bottom)
          - `ocr_text` string, nullable — Value extracted by OCR, if applicable. (only for internal purposes, may be removed in the future)
          - `ocr_raw_text` string, nullable — Raw value extracted by OCR, if applicable. (only for internal purposes, may be removed in the future)
          - `ocr_position` number[], nullable — OCR position, if applicable. (left, top, right, bottom) (only for internal purposes, may be removed in the future)
        - `validation_sources` ValidationSource[], required — See [Validation Source](#validation-source) for details.
        - `time_spent` number, float, required — Time spent while actively working on a given node, in seconds.
        - `time_spent_overall` number, float, required — Total time spent while validating a given node, in seconds. Only for internal purposes.
        - `no_recalculation` boolean — If set to true, the datapoint's formula is not recalculated automatically. Only available for datapoint category editable formula datapoints.
  - `grid` AnnotationContentGrid, required — Defines the grid structure for a multivalue object.
    - `parts` object[]
      - `page` number — A unique ID of a given object.
      - `columns` object[] — Grid columns.
        - `left_position` number, float — Position of the column left edge.
        - `schema_id` string, nullable — Reference to datapoint schema id. Used in grid-to-table conversion.
        - `header_texts` string[] — Extracted texts from column headers.
      - `rows` object[] — Grid rows.
        - `top_position` number, float — Position of the row top edge.
        - `tuple_id` number, nullable — ID of the corresponding tuple datapoint if it exists else null.
        - `type` string, nullable — Row type. Allowed values are specified in the schema. If `null`, the row is ignored during grid-to-table conversion.
      - `width` number, float — Total width of the grid.
      - `height` number, float — Total height of the grid.
  - `time_spent` number, float, required — Time spent while actively working on a given node, in seconds.
  - `time_spent_overall` number, float, required — Total time spent while validating a given node, in seconds. Only for internal purposes.
  - `time_spent_grid` number, float, required — Total time spent while actively working on a grid, in seconds. Only for internal purposes.
  - `time_spent_grid_overall` number, float, required — Total time spent while validating a given grid, in seconds. Only for internal purposes.

## Other responses

- `400` — Invalid input data.
- `401` — The username/password is invalid or token is invalid (e.g. expired).
- `403` — Insufficient permission, missing authentication, invalid CSRF token and similar issue.
- `404` — The specified resource was not found.
- `409` — Conflict
- `413` — Payload too large (especially for files uploaded).
- `429` — Request rate is too high, wait before sending more requests. See [Rate Limiting](/guides/overview#rate-limiting) for more details.
- `500` — Server failure while processing the request.
- `502` — Invalid response from the upstream server.
- `503` — We're temporarily offline for maintenance. Please try again later.
- `504` — Upstream server could not complete the request in time.

---

[API](https://skmtc.dev/rossum/apis/rossum-api.md) · [All operations](https://skmtc.dev/rossum/apis/rossum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rossum/rossum-api/revisions/f1b5a910991d/schema)