Skip to main content

Document APIs

These APIs are in beta

The document APIs are in beta and may have future breaking changes.

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

Document object​

Represents a document in Omni.

{
  "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"
}

List documents​

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

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

Parameters​

Note: All parameters must be provided as query parameters.

ParameterTypeRequiredDefaultDescription

include

string

No X

null

Comma-separated list of fields to include:

  • _count - Include favorite counts

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

folderId

string

No X

null

ID of the folder to filter results. Will only return documents within the specified folder.

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": [
    {
      "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",
      "_count": {
        "favorites": 5
      }
    }
  ]
}
FieldTypeDescription

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
}
IssueError 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
}
429 Too Many Requests

Results from too many requests in a given time frame. Refer to the Rate limiting documentation for more information.

500 Internal Server Error