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.
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.