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

Create a document​

Creates a document.

POST /api/unstable/documents
curl 'https://myorg.omniapp.co/api/unstable/documents' \
--H 'Authorization: Bearer <TOKEN>' \
--H 'Content-Type: application/json' \
--d '{
        "modelId": "3fb59130-54fc-4848-832f-d22f61933485",
        "name": "New Blobby Sales"
     }'

Parameters​

NameTypeRequiredDefaultDescription
modelIdstringYes ✓n/aThe ID of the model to build the document on
namestringYes ✓n/aThe name of the document
queryPresentationsarray of objectsNo Xn/aAn array of queryPresentation objects, each representing a query in the document's workbook

Response​

200 OK

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

200 OK
{
  "dashboard":{
     "id":"54665902-2c6d-4def-828b-1c0ff26e8ebd",
     "createdAt":"2025-03-11T17:47:37.602Z",
     "updatedAt":"2025-03-11T17:47:37.602Z",
     "metadata":{
        "layouts":{
           "lg":[
              {
                 "h":5,
                 "i":"1",
                 "w":6,
                 "x":0,
                 "y":0
              },
              {
                 "h":5,
                 "i":"2",
                 "w":6,
                 "x":6,
                 "y":0
              }
           ]
        },
        "textTiles":[
           
        ],
        "hiddenTiles":[
           
        ],
        "tileSettings":{
           
        },
        "tileFilterMap":{
           
        },
        "tileControlMap":{
           
        }
     },
     "metadataVersion":1,
     "refreshInterval":null,
     "facetFilters":false,
     "organizationId":"df290ed4-b721-4efe-914b-95d30ce1c5f2",
     "workbookId":"0d3eaaff-7558-41e7-af3e-8c625ce36510",
     "creatorId":"c5e5b577-8c64-48d4-8840-fbe41f924ae4",
     "updaterId":"c5e5b577-8c64-48d4-8840-fbe41f924ae4",
     "queryPresentationCollectionId":"09897dfb-0f93-41b3-8919-1c9a1d5e96bb",
     "dashboardId":"54665902-2c6d-4def-828b-1c0ff26e8ebd"
  },
  "workbook":{
     "id":"0d3eaaff-7558-41e7-af3e-8c625ce36510",
     "createdAt":"2025-03-11T17:47:37.494Z",
     "updatedAt":"2025-03-11T17:47:37.523Z",
     "deletedAt":null,
     "publishedAt":"2025-03-11T17:47:37.522Z",
     "isDraft":false,
     "identifier":"8bc04351",
     "name":"New Blobby Sales",
     "lastItemIndex":2,
     "ephemeral":"1:R0P-EHDd,2:VrAcHXM7",
     "organizationRole":null,
     "organizationAccessBoost":false,
     "publicRole":null,
     "publicAccessBoost":false,
     "canAnalyze":true,
     "canDownload":true,
     "canDrill":true,
     "canSchedule":true,
     "canUpload":true,
     "canViewWorkbook":false,
     "organizationId":"df290ed4-b721-4efe-914b-95d30ce1c5f2",
     "ownerId":"c5e5b577-8c64-48d4-8840-fbe41f924ae4",
     "updaterId":"c5e5b577-8c64-48d4-8840-fbe41f924ae4",
     "folderId":null,
     "originDocumentId":null,
     "documentId":"0d3eaaff-7558-41e7-af3e-8c625ce36510"
  }
}
400 Bad Request

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
Missing modelId parameterBad Request: modelId: Required
Missing name parameterBad Request: name: Required
429 Too Many Requests

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

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
  • labels - Include document labels

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.

userId

string

No X

null

UUID of a user to filter documents by. Returns only documents the specified user can view based on their permissions within the organization. The user must be a member of the organization.

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

Invalid userId format

Bad Request: userId: Invalid uuid

Unknown query parameter

Bad Request: formErrors: Unrecognized key(s) in object: '<unknownParameter>'

404 Not Found

Results from the provided creatorId or userId not being found. Note: An invalid uuid will result in a 400. In this situation, the provided ID 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

Delete a document​

Deletes the specified document. Deleted documents will be placed in the Trash.

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

Parameters​

Note: All parameters must be provided as query parameters.

ParameterTypeRequiredDefaultDescription

documentId

string

Yes ✓

n/a

The ID of the document to be deleted. To retrieve the ID, navigate to File > Document settings in the document and then click Settings. The Identifier field contains the document ID.

Response​

200 OK

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

{
    "success": true
}
404 Not Found

Returned when the specified document cannot be found:

{
    "detail": "Document with identifier \"<documentId>\" not found",
    "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.