Open API Documentation
| Item | Details |
|---|---|
| Best for | Resource management, file uploads, web collection, search, tags, and AI chat integrations |
| Current limits | Basic namespaces: 10 calls per 24 hours; Pro namespaces: 1,000 calls per 24 hours |
OmniBox Open API is a Bearer-token REST API for plugins, automation, system integration, and agent workflows. API keys can be limited to specific resources and permissions.
Use the API address and Swagger documentation for your deployment type:
| Address | Swagger Documentation | |
|---|---|---|
| Cloud Service | api.omnibox.pro | OmniBox Open API Docs |
| Local Deployment | <your-server>/open/api/ | <your-server>/open/api/docs |
Get API Key
See: How do I create an API Key
When creating an API key, you can add a remark. We recommend recording its purpose, caller, or related assistant so it is easier to manage and clean up later.
Both the web app and Mobile APP provide Settings > API Keys. The App supports creating, viewing, copying, editing, and deleting keys and configuring their permissions. See How do I create an API Key?.
API Key Permissions and Scope
New API keys default to Personal. Existing keys are never automatically widened. Users with a Team space may explicitly choose Personal + Team, covering their own Personal resources and Team resources they currently have permission to access within the same Namespace. Other members' Personal resources are excluded. Options follow the Team entry shown in the knowledge base: Team-related options are hidden when you are the only member and Team has no content.
Scope and save destination are separate. For creation, collection, and upload, an explicit parent_id takes precedence; otherwise an existing explicit assistant destination is preserved, with Personal as the fallback only when no destination was configured. An inaccessible or invalid destination returns an error instead of silently saving elsewhere. Updates and deletes affect the original resource in place.
When creating an API key, set both the Permission Scope and the specific permissions.
For a resource-specific key, the Permission Scope limits access to the selected file or folder and its descendants. New content defaults to that selected destination. Personal + Team uses the separate save-destination rules above.
In the API key list, OmniBox shows the specific resource permission scope. Click the resource name to open the corresponding resource details and confirm what the API key can access.

The supported permissions are:
| Permission | Actions | Description |
|---|---|---|
Resource Permissions | Create, read, update, delete | Manage files, folders, resource content, resource-tag associations, web collection, and file uploads |
Chat Permissions | Create | Call AI chat capabilities |
Tag Permissions | Create, read | Create and query tags |
Search Permissions | Read | Search resources within the API key scope |
If an API key does not have the required permission, the API returns an insufficient-permission error. We recommend selecting only the permissions your integration actually needs.
Use the Open API Skill in external agents
If you want an external agent, automation script, or internal tool to call OmniBox Open API, have the agent read the SKILL.md provided by OmniBox first. This file explains the Open API address, authentication method, permission scope, quota rules, and common calling workflows.
After loading the Open API Skill, an agent can recognize OmniBox resource links, namespace links, and share links, then use the link context with the corresponding Open API capabilities.
Cloud service URL:
https://api.omnibox.pro/v1/SKILL.mdFor self-hosted deployments, use your Open API access address, for example:
https://<your-domain>/open/api/v1/SKILL.mdUsage limits:
- Basic namespaces: 10 calls per 24 hours
- Pro namespaces: 1000 calls per 24 hours
Use Bearer Token authentication when calling the Open API:
Authorization: Bearer <api-key>Security note: do not write API keys into logs, documents, URLs, or chat context. For the full request parameters and response schemas, refer to the Swagger documentation and SKILL.md.
Read document comments
Use an API Key with resource read permission (resources:read) to read document comments, inline comments, and existing replies. The document must be inside the key's authorized scope and currently visible to the key owner, who must still belong to the space. This API is read-only.
Paths below are relative to the Open API v1 base (https://api.omnibox.pro/v1 for cloud, <your-server>/open/api/v1 for self-hosted):
GET /resources/<resource_id>/comment-threads?type=all&offset=0&limit=20
Authorization: Bearer <api-key>
GET /resources/<resource_id>/comment-threads/<thread_id>/comments?offset=1&limit=20
Authorization: Bearer <api-key>| Parameter | Default | Meaning |
|---|---|---|
type | all | Thread list only: all, document, or inline |
resolved | No filter | Thread list only: literal true or false |
offset | 0 | Nonnegative decimal integer |
limit | 20 | Decimal integer from 1 to 100 |
Each response contains items, total, offset, limit, and has_more. The thread list counts threads and previews one surviving comment per thread. Check comments_pagination: if has_more=true, use the comments endpoint from offset=1 to continue. You can also read a thread independently from offset=0. The second endpoint counts comments and returns page-specific mention_display_names. Continue both levels until their has_more values are false.
Threads and comments sort by creation time and then ID, ascending. Deleting the original message can leave a reply first. Offsets may shift when comments change between requests; complete traversal assumes stable data. An accessible document with no comments returns an empty list; an offset beyond the end returns an empty list with the actual total. Deleted data is excluded.
Document comments have anchor=null; inline anchors use editor positions and can be orphaned. Resolved threads are included by default. Author and creator expose nullable id and display_name, with retained display-name snapshots where available. Comment content retains mention shortcodes. Image-only comments may have empty text; attachment metadata includes only id, name, mimetype, and size. Attachment downloads, comment writes, and resolution changes are outside this API.
Both endpoints and each extra page consume the existing Open API quota. Failed requests may also consume quota. Errors: 400 invalid input, 401 invalid key, 403 scope/access denied, 404 missing document/thread or a thread from another document, 429 quota exhausted. Pagination rejects empty values, arrays/repeated parameters, fractions, negatives, and scientific notation.
The following Python example reads both levels. Set OMNIBOX_API_BASE to a base including /v1, OMNIBOX_API_KEY to your key, and OMNIBOX_RESOURCE_ID to the document ID. The key is read from the environment and never printed.
import json
import os
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen
base = os.environ['OMNIBOX_API_BASE'].rstrip('/')
key = os.environ['OMNIBOX_API_KEY']
resource_id = quote(os.environ['OMNIBOX_RESOURCE_ID'], safe='')
def get_json(path, params):
request = Request(
f'{base}{path}?{urlencode(params)}',
headers={'Authorization': f'Bearer {key}'},
)
with urlopen(request, timeout=30) as response:
return json.load(response)
thread_path = f'/resources/{resource_id}/comment-threads'
thread_offset = 0
while True:
page = get_json(thread_path, {'type': 'all', 'offset': thread_offset, 'limit': 20})
for thread in page['items']:
comments = list(thread['comments'])
metadata = thread['comments_pagination']
comment_offset = metadata['offset'] + len(comments)
while metadata['has_more']:
path = f"{thread_path}/{quote(thread['id'], safe='')}/comments"
reply_page = get_json(path, {'offset': comment_offset, 'limit': 100})
if not reply_page['items'] and reply_page['has_more']:
raise RuntimeError('Pagination made no progress')
comments.extend(reply_page['items'])
comment_offset = reply_page['offset'] + len(reply_page['items'])
metadata = reply_page
print(json.dumps({'thread_id': thread['id'], 'comments': comments}, ensure_ascii=False))
if not page['has_more']:
break
if not page['items']:
raise RuntimeError('Pagination made no progress')
thread_offset = page['offset'] + len(page['items'])