Skip to main content
GET
/
v1
/
documents
List documents
curl --request GET \
  --url https://{instance}.omniapp.co/api/v1/documents \
  --header 'Authorization: Bearer <token>'
{
  "pageInfo": {
    "hasNextPage": true,
    "nextCursor": "<string>",
    "pageSize": 123,
    "totalRecords": 123
  },
  "records": [
    {
      "connectionId": "<string>",
      "deleted": true,
      "folder": {
        "id": "<string>",
        "name": "<string>",
        "path": "<string>"
      },
      "hasDashboard": true,
      "identifier": "abc123",
      "name": "<string>",
      "owner": {
        "id": "<string>",
        "name": "<string>"
      },
      "updatedAt": "2023-11-07T05:31:56Z",
      "url": "https://org.omni.co/dashboards/abc123",
      "_count": {
        "favorites": 123,
        "views": 123
      },
      "labels": [
        "<string>"
      ],
      "description": "<string>"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Can be either an Organization API Key or Personal Access Token (PAT).

Include in the Authorization header as: Bearer YOUR_TOKEN

Query Parameters

​
include
string

Comma-separated list of additional fields to include in the response:

  • _count - Adds favorite and view count metrics

  • labels - Includes associated document labels

  • includeDeleted - Include deleted documents

  • onlyFavorites - Must be used with userId. Include only documents that the specified user has favorited.

  • onlySharedWithMe - Returns only documents explicitly shared with the specified user via documents permissions. Excludes documents owned by the user. Cannot be combined with ownerId or path.

    Additionally, depending on the type of API key being used:

    • Organization API keys require the userId parameter
    • Personal Access Tokens automatically infer the userId from the token
​
labels
string

Comma-separated list of labels to filter results. For example: finance,marketing

​
folderId
string<uuid>

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

​
pageSize
integer
default:20

Number of records per page

Required range: 1 <= x <= 100
​
sortField
enum<string>
default:name

Field to sort by:

  • favorites - Sort by the number of favorites
  • name - Sort by document name
  • updatedAt - Sort by last update time
  • visits - Sort by view count
Available options:
favorites,
name,
updatedAt,
visits
​
sortDirection
enum<string>
default:desc

Sort direction (asc for ascending, desc for descending)

Available options:
asc,
desc
​
cursor
string

Cursor for pagination. Used with sortField/sortDirection for relative positioning.

​
userId
string<uuid>

The ID of a standard or embed user to filter results, returning only documents the specified user can view based on their permissions.

If include=onlyFavorites is specified:

  • And using an Organization API key, this parameter is required
  • And using a Personal Access Token, the userId will be automatically inferred from the token
​
creatorId
string<uuid>

ID of the user who created the document(s), returning only documents that the specified user created.

Response

Paginated document list

​
pageInfo
object
required

Pagination information

​
records
object[]
required

List of documents