Sign in

v1

latestOpenAPI 3.1.02026-07-2618690613.4 KB
Documents

List documents

List documents with pagination and filtering

get/v1/documents

Query parameters

includestring

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
labelsstring

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

folderIdstring uuid

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

pageSizeinteger

Number of records per page

sortField'favorites' | 'name' | 'updatedAt' | 'visits'

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
sortDirection'asc' | 'desc'

Sort direction (asc for ascending, desc for descending)

cursorstring

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

userIdstring 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
creatorIdstring uuid

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

Response

Paginated document list

Example response

{
  "records": [
    {
      "identifier": "abc123",
      "url": "https://org.omni.co/dashboards/abc123"
    }
  ]
}