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
When creating an API key, set both the Permission Scope and the specific permissions.
The Permission Scope controls which part of the knowledge base the API key can access. When creating or editing an API key, you can browse and select a file or folder from a tree list. After you select it, the API key can only access that resource and its child content. If a create request does not specify a save location, the new resource is saved within this scope by default.
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.