canonical: https://jentic.com/apis/onna.com/onna

# Onna Platform API

Jentic publishes the only available OpenAPI specification for Onna Platform API, keeping it validated and agent-ready. Onna is a knowledge integration platform that ingests files, tickets, and other content from across an enterprise into a single, searchable workspace. The Platform API lets developers programmatically push resources into Onna using the resumable tus upload protocol, organise them into workspaces and folders, and attach custom fields for metadata. It is built for legal, compliance, and information governance teams who need to consolidate scattered enterprise data into a managed knowledge layer.

## For AI agents

Upload files and tickets into Onna workspaces, organise them with folders and custom fields, and authenticate using OAuth 2.0.

## Scope

Does not handle review workflows, redaction, or production exports inside the Onna UI - use for programmatic ingestion and organisation of resources only.

## Capabilities

- Create and manage workspaces that hold ingested resources
- Organise content into nested folders inside a workspace
- Upload files using the resumable tus protocol for large or unstable connections
- Ingest ticket-style records as resources alongside files
- Define custom fields at the workspace level and attach values to individual resources
- Authenticate via OAuth 2.0 with a developer-role token issued under the Enterprise plan

## Use cases

### Legal hold and ediscovery ingestion

Legal teams ingest custodian data from email, chat, and file shares into Onna so it can be searched and exported under a legal hold. The Platform API lets the ediscovery vendor or in-house tooling push files via tus uploads, attach matter-level custom fields, and organise everything into per-custodian folders. This replaces ad hoc data drops and gives ops a defensible chain of custody.

Example prompt: POST /workspaces to create a matter workspace, POST /folders for each custodian, then POST `/resources/files` with tus upload for each document.

### Compliance archive for regulated communications

Financial services and healthcare firms must archive communications and documents in a tamper-evident store. Onna ingests content from chat tools, email, and ticketing systems, and the Platform API is the integration point for proprietary or in-house systems that the standard connectors do not cover. Custom fields let compliance teams tag policy, retention, and review status at ingest time.

Example prompt: Create a compliance workspace, define a custom field for retention class, then ingest each archived message as a ticket resource with the retention class set.

### Knowledge consolidation across SaaS sprawl

Operations teams use Onna to bring together documents from many SaaS apps so internal teams can search one knowledge layer instead of ten. The Platform API is the way to integrate sources Onna does not have a native connector for, and to keep ingest running on a schedule. Most one-off connectors are built and shipped within a sprint.

Example prompt: List workspaces with GET /workspaces, pick the engineering workspace, create a folder per source, and ingest the source's exported files via tus uploads.

### AI agent enterprise ingestion through Jentic

An AI agent that assembles a knowledge base for a downstream RAG system can call Onna through Jentic to push files without holding the OAuth token. The agent searches Jentic for the upload operation, loads the schema, and uses the tus endpoints to stream large files reliably. Jentic injects the OAuth credential at execution time so the secret never enters the agent context.

Example prompt: Search Jentic for 'upload file to onna', load the POST `/resources/files` operation, and execute the resumable tus upload for a single document into a target workspace.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/oauth/token` | Exchange credentials for an OAuth access token |
| GET | `/workspaces` | List workspaces in the tenant |
| POST | `/workspaces` | Create a new workspace |
| POST | `/folders` | Create a folder in a workspace |
| POST | `/resources/files` | Register an uploaded file as a workspace resource |
| POST | `/upload/{id}/tus` | Start a resumable tus upload |
| POST | `/customFields` | Define a custom metadata field |

## Key resources

- **Workspaces** — Top-level containers for ingested content with their own custom field schema
- **Folders** — Nested organisation inside a workspace, scoped by onna_id
- **Resources: Files** — Uploaded file resources, created via tus and read or deleted by onna_id
- **Resources: Tickets** — Ticket-style structured resources for non-file content
- **CustomFields** — Workspace-level metadata schema attached to resources
- **Authentication** — OAuth 2.0 token endpoint and the matching user profile lookup
- **Upload (tus)** — Resumable upload protocol endpoints used to stream large files

## Why Jentic

- **Setup:** Wiring the Onna Platform API by hand means running the OAuth 2.0 flow at `/oauth/token`, refreshing access tokens, and building each workspace, folder, and resumable file upload against api.onna.com/v1 yourself. Through Jentic you install once, import the Onna Platform API from the API Directory, store the OAuth client credentials once, and your agent calls it with token refresh handled for you.
- **Permission scoping:** Onna passes workspace, folder, and file targets in the request body rather than the URL path, so you limit the agent to the operations it needs, such as uploading a file or reading workspaces. Creating workspaces or writing custom fields are excluded unless you add those operations to the allowed set.
- **Credential handling:** Your Onna OAuth client credentials and refresh token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a file to onna' or 'create an onna workspace', and Jentic returns the matching Onna operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Box API** — General-purpose enterprise content platform with broad collaboration features
- **Dropbox API v2** — Cloud file storage with strong sync and sharing primitives
- **HubSpot Files** — Marketing and sales file storage that may need ingesting into Onna

## FAQ

### Why is there no official OpenAPI spec for Onna Platform API?

Onna publishes its API documentation at dev.onna.com but does not ship a maintained OpenAPI specification on its own developer site. Jentic generates and maintains this spec so that AI agents and developers can call Onna via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Onna Platform API use?

Onna uses OAuth 2.0. The integration calls POST `/oauth/token` to exchange credentials for an access token and then includes that token on every other call. The account must be on an Enterprise plan and the calling user must have the Developer role assigned. Through Jentic, the OAuth credential is held in the vault and injected at execution time.

### How do I upload large files into Onna?

Use the tus resumable upload protocol exposed at POST `/upload/{id}/tus`, then PUT and PATCH the same path to stream chunks. This is the recommended path for any file larger than a few MB and is robust against network drops. POST `/resources/files` is used to register the file as a resource against a workspace once the upload completes.

### What are the rate limits for the Onna Platform API?

Onna does not publish a global rate limit in the OpenAPI spec. The platform applies per-tenant throttling and signals it through 429 responses, so integrations should back off on Retry-After. Bulk ingestion should use tus chunking and limit parallel uploads per workspace to avoid unnecessary throttling.

### How do I ingest documents into Onna through Jentic?

Install the SDK with 'pip install jentic', search for the operation with the query 'upload file to onna', then load the POST `/resources/files` operation, and execute it with the workspace onna_id and file metadata. Jentic handles the OAuth refresh and the tus upload sequence.

### Can I attach custom metadata to ingested resources?

Yes. Define the schema with POST /customFields and PATCH `/workspaces/{onna_id}/customFields/{field_id}`, then set the values on each resource at ingest time. This is how compliance teams tag matter, retention class, and review status without modifying the file payload.

### Can I limit what my agent is allowed to do with the Onna Platform API?

Yes. Because you run Jentic One yourself, your own rules decide which Onna operations and credentials the agent may use, so you can allow just the calls it needs, such as reading workspaces with GET /workspaces or uploading a file with POST `/resources/files` and the tus upload endpoints. Since Onna passes workspace, folder, and file targets in the request body rather than the URL path, you scope access at the operation level rather than by path. Operations like creating a workspace with POST /workspaces or defining metadata with POST /customFields stay excluded unless you add them to the allowed set.