omni-content-explorer

Omni Content Explorer

Find, browse, and organize Omni content — dashboards, workbooks, and folders — through the REST API.

Prerequisites

export OMNI_BASE_URL="https://yourorg.omniapp.co"
export OMNI_API_KEY="your-api-key"

API Discovery

When unsure whether an endpoint or parameter exists, fetch the OpenAPI spec:

curl -L "$OMNI_BASE_URL/openapi.json" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Use this to verify endpoints, available parameters, and request/response schemas before making calls.

Browsing Content

List All Content

curl -L "$OMNI_BASE_URL/api/v1/content" \
  -H "Authorization: Bearer $OMNI_API_KEY"

With Counts and Labels

curl -L "$OMNI_BASE_URL/api/v1/content?include=_count,labels" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Filter and Sort

# By label
curl -L "$OMNI_BASE_URL/api/v1/content?labels=finance,marketing" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# By scope
curl -L "$OMNI_BASE_URL/api/v1/content?scope=organization" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# Sort by popularity or recency
curl -L "$OMNI_BASE_URL/api/v1/content?sortField=favorites" \
  -H "Authorization: Bearer $OMNI_API_KEY"

curl -L "$OMNI_BASE_URL/api/v1/content?sortField=updatedAt" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Pagination

Responses include pageInfo with cursor-based pagination. Fetch next page:

curl -L "$OMNI_BASE_URL/api/v1/content?cursor={nextCursor}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Working with Documents

List Documents

curl -L "$OMNI_BASE_URL/api/v1/documents" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# Filter by creator
curl -L "$OMNI_BASE_URL/api/v1/documents?creatorId={userId}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Each document includes: identifier, name, type, scope, owner, folder, labels, updatedAt, hasDashboard.

Important: Always use the identifier field for API calls, not id. The id field is null for workbook-type documents and will cause silent failures.

Get Document Queries

Retrieve query definitions powering a dashboard's tiles:

curl -L "$OMNI_BASE_URL/api/v1/documents/{identifier}/queries" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Useful for understanding what a dashboard computes and re-running queries via omni-query.

Folders

# List
curl -L "$OMNI_BASE_URL/api/v1/folders" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# Create
curl -L -X POST "$OMNI_BASE_URL/api/v1/folders" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q1 Reports", "scope": "organization" }'

Labels

# List labels
curl -L "$OMNI_BASE_URL/api/v1/labels" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# Add label to document
curl -L -X PUT "$OMNI_BASE_URL/api/v1/documents/{identifier}/labels/{labelName}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# Remove label
curl -L -X DELETE "$OMNI_BASE_URL/api/v1/documents/{identifier}/labels/{labelName}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Favorites

# Favorite
curl -L -X PUT "$OMNI_BASE_URL/api/v1/documents/{identifier}/favorite" \
  -H "Authorization: Bearer $OMNI_API_KEY"

# Unfavorite
curl -L -X DELETE "$OMNI_BASE_URL/api/v1/documents/{identifier}/favorite" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Dashboard Downloads

# Start download (async)
curl -L -X POST "$OMNI_BASE_URL/api/v1/dashboards/{dashboardId}/download" \
  -H "Authorization: Bearer $OMNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "pdf" }'

# Poll job status
curl -L "$OMNI_BASE_URL/api/v1/jobs/{jobId}/status" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Formats: pdf, png

URL Patterns

Construct direct links to content:

Dashboard: {OMNI_BASE_URL}/dashboards/{identifier}
Workbook:  {OMNI_BASE_URL}/w/{identifier}

The identifier comes from the document's identifier field in API responses. Always provide the user a clickable link after finding content.

Search Patterns

When scanning all documents for field references (e.g., for impact analysis), paginate with cursor and call GET /api/v1/documents/{identifier}/queries for each document. Launch multiple query-fetch calls in parallel for efficiency. For field impact analysis, prefer the content-validator approach in omni-model-explorer.

Docs Reference

• Content API · Documents API · Folders API · Labels API · Dashboard Downloads

Related Skills

• omni-query — run queries behind dashboards you've found
• omni-content-builder — create or update dashboards
• omni-embed — embed dashboards you've found in external apps
• omni-admin — manage permissions on documents and folders