Document APIs

The document APIs allow you to interact with documents in Omni.

Document object

Represents a document in Omni.

Example

{
  "connectionId": "c0f12353-4817-4398-bcc0-d501e6dd2f64",
  "deleted": false,
  "folder": {
    "id": "ce3b1dcd-c768-4f01-a479-353325c4c5b0",
    "name": "In Progress Reports",
    "path": "in-progress-reports",
    "scope": "organization"
  },
  "identifier": "12db1a0a",
  "labels": [
    {
      "name": "Marketing",
      "verified": false
    }
  ],
  "name": "Blob Web Traffic",
  "owner": {
    "id": "9e8719d9-276a-4964-9395-a493189a247c",
    "name": "Blobby"
  },
  "scope": "public",
  "type": "document",
  "updatedAt": "2025-01-07T10:00:00Z"
}

Fields

Field	Type	Description
connectionId	string	ID of the database connection the document is built on
deleted	boolean	Whether the document has a non-normal status
folder	object	Folder details. Will be null if the document isn't in a folder.
folder.id	string	Unique identifier of the folder
folder.name	string	Name of the folder (1-255 characters)
folder.path	string	Path of the folder
folder.scope	string	Scope of the folder: restricted organization public
identifier	string	Unique identifier of the document. Corresponds to the Identifier field in the document's settings.
labels	array of objects	Labels associated with the document
labels.name	string	Name of the label
labels.verified	boolean	Whether the label is verified
name	string	Name of the document
owner	object	Details about the document owner
owner.id	string	UUID of the user that owns the document
owner.name	string	Name of the owner
scope	string	Document scope, indicating the level of access the document has: restricted organization public
type	string	Type of content, always set to document
updatedAt	string	ISO-8601 formatted date-time of last update

List documents

Retrieves a paginated list of document items. This endpoint supports filtering, sorting, and cursor-based pagination.

Basic request

GET /api/unstable/documents

curl 'https://myorg.omniapp.co/api/unstable/documents' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Filters & sorting

GET /api/unstable/documents?labels=<labels>&pageSize=<size>&sortField=<field>&sortDirection=<direction>

curl 'https://myorg.omniapp.co/api/unstable/documents?labels=finance,marketing&pageSize=10&sortField=updatedAt&sortDirection=desc' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Pagination with cursor

GET /api/unstable/documents?cursor=<documentName>&pageSize=<size>

curl 'https://myorg.omniapp.co/api/unstable/documents?cursor=Product Totals&pageSize=20' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json'

Parameters

Note: All parameters must be provided as query parameters.

Parameter	Type	Required	Default	Description
cursor	string	No X	null	Cursor for pagination. Used with sortField/sortDirection for relative positioning.
pageSize	number	No X	20	The number of items to retrieve per page: Minimum - 1 Maximum - 100
sortField	string	No X	desc	Field to sort by. Must be one of the following: favorites - Sort by the number of favorites name - Sort by document name updatedAt - Sort by last update time visits - Sorts by view count
sortDirection	string	No X	desc	Direction to sort results. Must be asc (ascending) or desc (descending).
labels	string	No X	null	Comma-separated list of labels to filter results. For example: finance,marketing
creatorId	string	No X	null	UUID of the user who created the document(s). Retrieve user IDs with the List users and Retrieve a user endpoints.

Response

200 OK

Successful requests will return a 200 OK status and a response body similar to the following:

{
  "pageInfo": {
      "hasNextPage": true,
      "nextCursor": "Product Totals",
      "pageSize": 20,
      "totalRecords": 58
  },
  "records": [
      {}
}

Field	Type	Description
records	array of objects	An array of document objects that meet the provided filters, if provided.
pageInfo	object	An object containing information about the current page of results.
pageInfo.hasNextPage	boolean	If true, another page of results exists.
pageInfo.nextCursor	string	The name of the document that begins the next page of results. Provide this value as the cursor to retrieve the next page.
pageInfo.pageSize	string	The total number of items on the current page.
pageInfo.totalItems	number	The total number of items in the results set, across all pages.

400 Bad Request

Results from invalid request parameters. Response bodies will be an object similar to the following:

{
  "detail": "<errorReason>",
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": 400
}

Issue	Error detail
pageSize cannot be 0	Bad Request: pageSize: Page size must be at least 1
pageSize cannot exceed 100	Bad Request: pageSize: Page size cannot exceed 100
Invalid sortField	Bad Request: sortField: Invalid enum value. Expected 'favorites' | 'name' | 'updatedAt' | 'visits', received '<invalidField>'
Invalid creatorId format	Bad Request: creatorId: Invalid uuid
Unknown query parameter	Bad Request: formErrors: Unrecognized key(s) in object: '<unknownParameter>'

404 Not Found

Results from the provided creatorId not being found. Note: An invalid uuid will result in a 400. In this situation, the provided creatorId is a valid uuid, but it cannot be found.

Response bodies will be an object similar to the following:

{
  "detail": "User with id <uuid> does not exist",
  "schemas": [
      "urn:ietf:params:scim:api:messages:2.0:Error"
  ],
  "status": 404
}

500 Internal Server Error