Skip to main content
API docs by Redocly

Onna Platform API (v1.1.0)

Download OpenAPI specification:Download

URL: https://dev.onna.com/help License: Apache 2.0 Terms of Service

Introduction

The Onna Platform API enables you to programmatically upload your data into our Knowledge Integration Platform. This unlocks the possibility to have all your data in one place and turn it into knowledge—even data we don't support directly with one of our connectors.

Key concepts

Before starting to use the API, we recommend to become familiar with some key concepts. For more information on the key concepts, see API basics.

Requirements

To use this API, you must have an active account on an Enterprise Plan and have the Developer role assigned.

For more information, see Requirements.

Security

This API requires that all requests are made using HTTPS and must be authenticated with a valid token.

Response codes

A full list of the response codes returned by this API is available at Response codes.

Versioning

This API uses semantic versioning to ensure that your client doesn't break. The version is declared in the URL so that you can lock to a specific one by prefix the URL.

When the version declared in the URL is not supported, you will receive a 400 response.

For more information, see Versioning.

Date and time format

This API supports dates and times in ISO 8601 format.

Pagination

This API uses cursoring to divide large sets of results in multiple pages. For more information, see Pagination.

Parameters

There are many ways to pass parameters when making requests to this API. For more information, see Parameters.

Resource types

You can ingest various type of resources. For more information, see Resource types.

Authentication

Our API uses OAuth 2's Client Credentials Grant to authenticate your requests. This grant type is especially suited for machine-to-machine (M2M) applications, such as the applications you build on top of the Onna platform.

For more information please check our detailed authentication docs.

Login

Exchange credentials for an access token.

Authorizations:
OAuth2
Request Body schema: application/x-www-form-urlencoded
client_id
string (Client ID)

Unique client ID, generated in the Platform API app.

client_secret
string (Client Secret)

Unique client secret, generated in the Platform API app.

Grant Type (string) or Grant Type (null) (Grant Type)
Default: "client_credentials"

Use the default value.

Responses

Request samples 

curl --request POST \
  --url 'https://api.onna.com/v1/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'grant_type=client_credentials'

Response samples

Content type
application/json
{
  • "access_token": "<BEARER_TOKEN>",
  • "expires_in": 3599,
  • "token_type": "bearer"
}

Current User

Return information about the currently authenticated user.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "example": {
    }
}

Workspaces

Workspaces are locations where you can collect data coming from different sources, organize it, and collaborate with other members of your team.

You can share workspaces with collaborators with various permission levels and roles. Permission levels are dependent on the type of expected collaboration. You can also search across an entire workspace and export the results of your searches or entire data collections.

This collection includes all the endpoints that enable you to work and collaborate inside workspaces.

List Workspaces

List workspaces.

Authorizations:
OAuth2
query Parameters
Cursor (string) or Cursor (null) (Cursor)
Examples: cursor=2022-02-22T11:11:11.12345
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location --request GET 'https://api.onna.com/v1/workspaces?cursor=100' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "items": [
    ]
}

Create Workspace

Create a workspace.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Description (string) or Description (null) (Description)

Short description of the workspace.

Embeddings Enabled (boolean) or Embeddings Enabled (null) (Embeddings Enabled)

Flag to enable or disable embeddings calculation for the workspace.

name
required
string (Name)

Display name of the workspace.

Array of Tags (strings) or Tags (null) (Tags)

Labels attached to the workspace for the purpose of identification or to give meta information.

Responses

Request samples

Content type
application/json
{
  • "description": "My personal workspace",
  • "embeddings_enabled": true,
  • "name": "My workspace",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "onna_id": "ws6f0c5339de42f9964e6afe9bf20469",
  • "type": "BoxEDatasource"
}

Delete Workspace

Delete a Workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location --request DELETE 'https://api.onna.com/v1/workspaces/ws6f0c5339de42f9964e6afe9bf20469' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Retrieve Workspace Info

Retrieve information related to a workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location --request GET 'https://api.onna.com/v1/workspaces/ws6f0c5339de42f9964e6afe9bf20469' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json

Response samples

Content type
application/json
{
  • "creation_datetime": "2025-04-29T08:51:06.803407+00:00",
  • "description": "My personal workspace",
  • "modification_datetime": "2025-04-29T08:51:06.803407+00:00",
  • "name": "My workspace",
  • "onna_id": "ws6f0c5339de42f9964e6afe9bf20469",
  • "tags": [
    ]
}

Update Workspace

Update the workspace. For example, rename it from my-workspace to my-new-workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Description (string) or Description (null) (Description)

Short description of the workspace.

Embeddings Enabled (boolean) or Embeddings Enabled (null) (Embeddings Enabled)

Flag to enable or disable embeddings calculation for the workspace.

Name (string) or Name (null) (Name)

Display name of the workspace.

Array of Tags (strings) or Tags (null) (Tags)

Labels attached to the workspace for the purpose of identification or to give meta information.

Responses

Request samples

Content type
application/json
{
  • "description": "My personal workspace",
  • "embeddings_enabled": true,
  • "name": "My workspace",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List Workspace Custom Fields

List custom fields for a workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

query Parameters
Cursor (string) or Cursor (null) (Cursor)
Examples: cursor=2022-02-22T11:11:11.12345
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/workspaces/0c5dfdeb9df34e44a754975a2ad9473d/customFields' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "items": [
    ]
}

Enable Workspace Custom Field

Enable custom field for a workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
onna_id
required
string (Onna ID)

Alphanumeric unique identifier of the workspace.

Responses

Request samples

Content type
application/json
{
  • "onna_id": "cf-b20696ae9"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Read Workspace Custom Value

Get custom field value for a workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

field_id
required
string (Field ID)
Examples: cf-b20696ae9

Unique ID of the field.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location 'https://stage.intra.onna.internal/api/v1/workspaces/0c5dfdeb9df34e44a754975a2ad9473d/customFields/cf-testdates' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{
  • "onna_id": "cf-b20696ae9",
  • "value": "My custom field value"
}

Update Workspace Custom Value

Set custom field value for a workspace.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Workspace ID)
Examples: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

field_id
required
string (Field ID)
Examples: cf-b20696ae9

Unique ID of the field.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
value
required
string (Value)

Custom field value

Responses

Request samples

Content type
application/json
{
  • "value": "My custom field value"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Collections

Collections are designed to facilitate the management and collaboration of data within workspaces. Workspaces serve as centralized locations where data from multiple sources can be organized and shared with team members.

Collaborators can be assigned different roles and permissions based on collaboration needs. These endpoints allow searching across the workspace and exporting results or entire data collections.

This collection provides all necessary endpoints to enable seamless collaboration and efficient data handling within workspaces.

List Collections

List all collections.

Authorizations:
OAuth2
query Parameters
Cursor (string) or Cursor (null) (Cursor)
Examples: cursor=2022-02-22T11:11:11.12345
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/collections' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Accept: application/json' \

Response samples

Content type
application/json
{
  • "cursor": "2022-02-22T11:11:11.12345",
  • "items": [
    ]
}

Create Collection

Create a collection in a workspace.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Config Type (string) or Config Type (null) (Config Type)

The configuration type for the collection, required for certain datasource types (e.g., Box).

credential_id
required
string (Credential Id)

Wallet ID containing service account credentials.

Array of Data Types (strings) or Data Types (null) (Data Types)

Data types to sync for Google Workspace collections (e.g., ['resources', 'preservation']).

Array of Datasource Types (strings) or Datasource Types (null) (Datasource Types)

Datasource types to include for collections (e.g., ['GMailDatasource', 'GDriveEDatasource']).

From Date (string) or From Date (null) (From Date)

Start date for collection data range in ISO format (YYYY-MM-DD). Optional.

name
required
string (Name)

Display name of the Collection.

onna_parent_id
required
string (Parent ID)

The ID of the parent Workspace.

Skip Spam And Trash (boolean) or Skip Spam And Trash (null) (Skip Spam And Trash)

Whether to skip spam and trash folders for Gmail sync.

Sync Filters (object) or Sync Filters (null) (Sync Filters)

Sync filters configuration for Google Workspace collections.

To Date (string) or To Date (null) (To Date)

End date for collection data range in ISO format (YYYY-MM-DD). Optional. Note: Some connectors like Box may only support from_date.

type
required
string (Type)
Type Sync (string) or Type Sync (null) (Type Sync)

Sync type for Google Workspace collections (e.g., 'arch', 'one').

Username (string) or Username (null) (Username)

Username for Google Workspace collections (typically an email).

Responses

Request samples

Content type
application/json
Example
{
  • "credential_id": "wallet_id_here",
  • "from_date": "2023-01-01",
  • "name": "My ebox collection",
  • "onna_parent_id": "b7c6f55fa54c4a3e821e825bd6262c0f",
  • "to_date": "2023-12-31",
  • "type": "office365"
}

Response samples

Content type
application/json
{
  • "onna_id": "f3fb1c53300a4127945274779272d4b0",
  • "type": "ebox"
}

Authenticate Source

Authenticate to a given source type.

Authorizations:
OAuth2
path Parameters
source_type
required
string (Source Type)
Enum: "s3" "box" "ebox" "confluence" "dropbox" "edropbox" "gcs" "gdrive" "egdrive" "github" "gmail" "gcalendar" "gsuite" "gvault" "imap" "jira" "eworkplace" "miro" "msteams" "emsteams" "office365" "okta" "onedrive" "eonedrive" "mgraphmail" "quip" "equip" "salesforce" "sharepoint" "slack" "eslack" "twitter" "zendesk" "zoom" "slackjson" "logikcull" "gemini" "echatgpt" "MicrosoftE"

Source to authenticate to.

query Parameters
redirect_to
required
string (Redirect To)

Final URL to redirect to.

Scopes Type (string) or Scopes Type (null) (Scopes Type)

Type of scopes to request. Use 'preservation' for legal hold flows.

State (string) or State (null) (State)

Optional state string to pass through the OAuth flow.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location 'https://api.onna.com/v1/collections/authorization_url/<SOURCE_TYPE>?redirect_to=<YOUR_CALLBACK>' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
null

Create Collection From Hold

Create a collection based on a hold

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
End Date (string) or End Date (null) (End Date)

End date for collection data range in ISO format (YYYY-MM-DD).

matter_id
required
string (Matter Id)

Matter ID to associate the collection with, defining this will create the collection within the matter workspace. It will also automatically configure the sync filters based on the sources defined within this matter.

Source Id (string) or Source Id (null) (Source Id)

Source ID to associate the collection with, defining this will create the collection within the source's matter workspace. It will also automatically configure the sync filters based on the source.

Start Date (string) or Start Date (null) (Start Date)

Start date for collection data range in ISO format (YYYY-MM-DD).

Responses

Request samples

Content type
application/json
{
  • "end_date": "string",
  • "matter_id": "string",
  • "source_id": "string",
  • "start_date": "string"
}

Response samples

Content type
application/json
{
  • "collections": [ ],
  • "errors": { }
}

Delete Collection

Delete the collection. 📌 This also deletes all resources contained in it!

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request DELETE \
--url 'https://api.onna.com/v1/collections/fd9f0c5339de42f9964e6afe9bf20259' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Retrieve Collection Info

Retrieve information related to a collection.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/fd9f0c5339de42f9964e6afe9bf20259' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json' \

Response samples

Content type
application/json
{
  • "configured": false,
  • "name": "My new collection",
  • "onna_id": "f3fb1c53300a4127945274779272d4b0",
  • "sync_status": "created",
  • "type": "ebox",
  • "type_sync": "one"
}

Update Collection

Update the collection. For example, rename it from My collection to My updated collection name.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json

The request shape depends on the existing collection type. Google Workspace collections accept typed Google sync filters, while all other collection types accept generic sync filter objects. The API derives the collection type from the collection being updated, so clients do not send a discriminator field in the PATCH body.

One of
Credential Id (string) or Credential Id (null) (Credential Id)

Optional wallet ID containing service account credentials.

Array of Data Types (strings) or Data Types (null) (Data Types)

The data types for the collection.

Array of Datasource Types (strings) or Datasource Types (null) (Datasource Types)

The datasource types to be created.

From Date (string) or From Date (null) (From Date)

Start date for collection data range in ISO format (YYYY-MM-DD).

Name (string) or Name (null) (Name)

Display name of the Collection.

Skip Spam And Trash (boolean) or Skip Spam And Trash (null) (Skip Spam And Trash)

Skip spam and trash folders for Google Workspace.

any or null

Sync filters for the collection. For detailed configuration guide and examples, see Sync Filters Documentation.

Sync Status (string) or Sync Status (null) (Sync Status)

The sync status of the collection.

To Date (string) or To Date (null) (To Date)

End date for collection data range in ISO format (YYYY-MM-DD).

Type Sync (string) or Type Sync (null) (Type Sync)

The sync type of the collection (one, arch or auto).

Username (string) or Username (null) (Username)

Username for Google Workspace collections.

Responses

Request samples

Content type
application/json
Example
{
  • "credential_id": "wallet_id_here",
  • "name": "My updated collection name",
  • "sync_filters": {
    },
  • "sync_status": "pending",
  • "type_sync": "one"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

List of channels

Get list of channels

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

query Parameters
Team ID (string) or Team ID (null) (Team ID)

ID of the parent resource to get channels for (MS Teams only).

Array of Types (strings) or Types (null) (Types)

Filter channels by type, e.g. public, private (Slack only).

Array of Teams (strings) or Teams (null) (Teams)

Filter by Slack team IDs (Slack only).

User (string) or User (null) (User)

Slack user ID to list channels for (Slack only, required).

include_shared
boolean (Include shared)
Default: false

Legacy alias for include_workspace_shared_selected (Slack only).

include_workspace_shared_selected
boolean (Include workspace shared selected)
Default: false

Slack only.

include_workspace_shared_all
boolean (Include workspace shared all)
Default: true

Slack only.

include_external_shared
boolean (Include external shared)
Default: true

Slack only.

only_ext_shared
boolean (Only external shared)
Default: false

Slack only.

Limit (integer) or Limit (null) (Limit)
Default: 1000

Max channels to return (Slack only).

Offset (string) or Offset (null) (Offset)

Pagination cursor (Slack only).

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/a859397e23bd44d6a5e7a9f68b9f9ae9/channels?team_id=team123' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
Example
{
  • "channels": [
    ],
  • "cursor": "string"
}

List of folders

Get list of Folders from the 3rd party service.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

query Parameters
Query (string) or Query (null) (Query)

Search query to filter folders by name.

User ID (string) or User ID (null) (User ID)

ID of the a user to search for folders for.

Folder ID (string) or Folder ID (null) (Folder ID)

ID of the parent folder to search within.

Limit (integer) or Limit (null) (Limit)
Default: 100

Number of results to return.

Offset (string) or Offset (null) (Offset)

Offset/cursor for pagination.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/a859397e23bd44d6a5e7a9f68b9f9ae9/folders' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
Example
{
  • "_next": "string",
  • "results": [
    ],
  • "total_count_label": "string"
}

Pair credential with Source.

Pair a credential to a source.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

query Parameters
auth_code
required
string (Auth Code)

Authorization code from source.

Tenant (string) or Tenant (null) (Tenant)

Microsoft tenant ID (required for Teams collections).

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location --request POST 'https://api.onna.com/v1/collections/<COLLECTION_ID>/pair_credentials?auth_code=<AUTH_CODE>' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Start Sync

Start the sync process for the collection.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
null

Retrieve Collection Sync Status

Get comprehensive sync status information for a collection,including ingestion, processing, and summary metrics.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/{onna_id}/sync-status' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json'

Response samples

Content type
application/json
Example
{
  • "datasource_ids": [
    ],
  • "ingestion_started_at": "2025-12-08T13:08:38.865820",
  • "ingestion_status": "synced",
  • "initial_collection_status": "failed",
  • "initial_ingestion_complete": true,
  • "initial_ingestion_completed_at": "2025-12-08T14:39:09.542177",
  • "initial_processing_completed_at": "2025-12-08T17:44:33.826592",
  • "initial_sync_ready": true,
  • "processing_status": "failed",
  • "summary": {
    }
}

List Google Team Drives

List Google Team Drives. This requires calling Sync Google Team Drives first.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

query Parameters
Cursor (string) or Cursor (null) (Cursor)

Pagination cursor for retrieving additional results.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/{onna_id}/team-drives' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{
  • "cursor": 0,
  • "total": 0,
  • "values": {
    }
}

Sync Google Team Drives

Initiate Google Workspace team drives synchronization. Must be called before listing team drives. Returns a task ID which you can track using Get Job Status.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request POST \
--url 'https://api.onna.com/v1/collections/{onna_id}/team-drives/sync' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{}'

Response samples

Content type
application/json
{ }

List Google Team Drive Children

Get children folders within a Google Workspace team drive.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

team_drive_id
required
string (Team Drive ID)

ID of the team drive to get children for.

query Parameters
Root Team Drive ID (string) or Root Team Drive ID (null) (Root Team Drive ID)

Root team drive ID. Optional parameter for nested team drives.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/{onna_id}/team-drives/{team_drive_id}?rootTeamDrive={root_team_drive_id}' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{
  • "children": [
    ]
}

List of Teams

Get list of Teams

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

query Parameters
Offset (string) or Offset (null) (Offset)

Offset/cursor for pagination (Miro only).

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/a859397e23bd44d6a5e7a9f68b9f9ae9/teams' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
Example
{
  • "property1": [
    ],
  • "property2": [
    ]
}

List of users

Get list of Users from the 3rd party service.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

query Parameters
Limit (integer) or Limit (null) (Limit)

Number of results to return. Defaults to 1000; Miro caps at 100 (also its default).

Offset (string) or Offset (null) (Offset)

Offset/cursor for pagination.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/a859397e23bd44d6a5e7a9f68b9f9ae9/users' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
Example
{
  • "limit": 0,
  • "offset": "string",
  • "users": [
    ]
}

Get Slack workspace

Get Slack workspace

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the collection.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/collections/a859397e23bd44d6a5e7a9f68b9f9ae9/workspaces' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{
  • "cache_ts": 0,
  • "ok": true,
  • "team": {
    }
}

Folders

Folders are containers for your files or other folders. A place where you can group your resources together, like in any desktop operating system.

This collection includes all the endpoints that enable you to handle folders, such as creating, retrieving, or deleting them.

Create Folder

Create a folder in a workspace.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
name
required
string (Name)

Display name of the Folder.

onna_parent_id
required
string (Parent ID)

The ID of the parent Workspace or Folder.

Responses

Request samples

Content type
application/json
{
  • "name": "My folder",
  • "onna_parent_id": "b7c6f55fa54c4a3e821e825bd6262c0f"
}

Response samples

Content type
application/json
{
  • "onna_id": "8a8ead66ba6f4862b922a911dd67c439"
}

Delete Folder

Delete the folder. 📌 This also deletes all resources contained in it!

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the folder.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request DELETE \
--url 'https://api.onna.com/v1/folders/fd9f0c5339de42f9964e6afe9bf20259' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Retrieve Folder Info

Retrieve information related to a folder.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the folder.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/folders/fd9f0c5339de42f9964e6afe9bf20259' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json' \

Response samples

Content type
application/json
{
  • "name": "My folder",
  • "onna_id": "fd9f0c5339de42f9964e6afe9bf20259"
}

Update Folder

Update the folder. For example, rename it from My folder to My updated folder name.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the folder.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
name
required
string (Name)

Display name of the Folder.

Responses

Request samples

Content type
application/json
{
  • "name": "My updated folder name"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Resources: Files

You can ingest a wide range of raw files.

Here's the details of what raw files you can view in the UI:

  • Media (Audio, Video, Images)
  • PDFs
  • Microsoft Documents (DOC, DOCX, PPT, PPTX), rendered as PDFs
  • Microsoft Spreadsheets (Worksheets rendered as tabs)
  • Plain text (CSV, TXT), rendered as PDFs
  • Emails (EML, MSG)
  • Web pages (HTM, HTML)
  • Code

For more information,please check our docs about raw-files ingestion.

Create File

Create a file resource.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Comment (string) or Comment (null) (Comment)

Comment type of file.

Creation Date (string) or Creation Date (null) (Creation Date)

Date when file was created.

Creator (string) or Creator (null) (Creator)

User that created the file.

Deleter (string) or Deleter (null) (Deleter)

User that deleted the file.

Deletion Date (string) or Deletion Date (null) (Deletion Date)

Date when file was deleted.

Description (string) or Description (null) (Description)

File description.

Name (string) or Name (null) (Name)

File name.

onna_parent_id
required
string (Parent ID)

The ID of the parent Workspace or Folder.

Array of Origin Tags (strings) or Origin Tags (null) (Origin Tags)

List of tags associated to the file in the origin.

Path (string) or Path (null) (Path)

Path to file, at the origin.

ref
required
string (Reference)

The Reference Number or ID for the file at the origin.

Share URL (string) or Share URL (null) (Share URL)

Link or invite to share file (at origin).

Status (string) or Status (null) (Status)

File status: Deleted, Archived, etc.

Type (string) or Type (null) (Type)

Type of file.

Update Date (string) or Update Date (null) (Update Date)

Date when the file was last updated.

Updater (string) or Updater (null) (Updater)

The last user to update the file.

url
required
string (URL)

A Unique Resource Locator for the file at the origin.

Version (string) or Version (null) (Version)

Version.

Responses

Request samples

Content type
application/json
{
  • "comment": "Creative Commons PDF",
  • "creation_date": "2022-07-21T09:02:40.083388+00:00",
  • "creator": "Creative Commons ORG",
  • "description": "Creative Commons PDF",
  • "name": "Creativecommons-what-is-creative-commons_eng.pdf",
  • "onna_parent_id": "0ec85634bf2c4d8db453a65551c36b8d",
  • "origin_tags": [
    ],
  • "path": "/images/3/35",
  • "ref": "Creativecommons-what-is-creative-commons_eng",
  • "type": "pdf",
  • "update_date": "2022-07-21T09:02:40.083388+00:00",
  • "updater": "Bob",
  • "url": "https://wiki.creativecommons.org/images/3/35/Creativecommons-what-is-creative-commons_eng.pdf"
}

Response samples

Content type
application/json
{
  • "onna_id": "string"
}

Delete File

Delete the file.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the file.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request DELETE 'https://api.onna.com/v1/resources/files/fs3f0c5339de42f9964e6afe9bf20169' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Read File

Retrieve a file resource.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the file.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/resources/files/fs3f0c5339de42f9964e6afe9bf20169' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "comment": "Creative Commons PDF",
  • "creation_date": "2022-07-21T09:02:40.083388+00:00",
  • "creator": "Creative Commons ORG",
  • "description": "Creative Commons PDF",
  • "name": "Creativecommons-what-is-creative-commons_eng.pdf",
  • "onna_parent_id": "0ec85634bf2c4d8db453a65551c36b8d",
  • "origin_tags": [
    ],
  • "path": "/images/3/35",
  • "ref": "Creativecommons-what-is-creative-commons_eng",
  • "type": "pdf",
  • "update_date": "2022-07-21T09:02:40.083388+00:00",
  • "updater": "Bob",
  • "url": "https://wiki.creativecommons.org/images/3/35/Creativecommons-what-is-creative-commons_eng.pdf"
}

Update File

Update a file resource.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (File ID)

Unique ID of the file resource.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Array of Tags (strings) or Tags (null) (Tags)

List of onna tags to update for the file.

Any of
Array
string

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Resources: Tickets

The Ticket resource type defines resources with which two parties communicate to track work to resolve issues or deliver incremental value. Customer support requests, service desk tickets, or software development projects are some examples of what can be mapped to this resource type.

Read our developer documentation to learn more about the Ticket resource type.

Create Ticket

Create a ticket resource.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Assignee Group (string) or Assignee Group (null) (Assignee Group)

Assignee group.

Array of Assignees (strings) or Assignees (null) (Assignees)

List of users assigned to the ticket.

Author (string) or Author (null) (Author)

The user that created the ticket.

Category (string) or Category (null) (Category)

Category.

Array of Comments (objects) or Comments (null) (Comments)

List of messages associated to the ticket.

Creation Date (string) or Creation Date (null) (Creation Date)

Date when the ticket was created.

Description (string) or Description (null) (Description)

Description.

Array of Followers (strings) or Followers (null) (Followers)

List of users following the ticket.

name
required
string (Name)

Title.

onna_parent_id
required
string (Parent ID)

The ID of the parent Folder.

Array of Origin Tags (strings) or Origin Tags (null) (Origin Tags)

List of tags associated to the ticket in the origin.

Priority (string) or Priority (null) (Priority)

Priority: high, medium, low, etc.

Array of Reactions (strings) or Reactions (null) (Reactions)

List of reactions.

ref
required
string (Reference)

The Reference Number or ID for the ticket at the origin.

Requester (string) or Requester (null) (Requester)

The user that requested the ticket.

Severity (string) or Severity (null) (Severity)

Severity: high, medium, low, etc.

Status (string) or Status (null) (Status)

Ticket status: open, closed, archived, etc.

Subcategory (string) or Subcategory (null) (Subcategory)

Subcategory.

Type (string) or Type (null) (Type)

Type of ticket.

Update Date (string) or Update Date (null) (Update Date)

Date when the ticket was last updated.

Updater (string) or Updater (null) (Updater)

The last user to update the ticket.

url
required
string (URL)

A Unique Resource Locator for the ticket at the origin.

Responses

Request samples

Content type
application/json
{
  • "assignee_group": "IT Support",
  • "assignees": [
    ],
  • "author": "Bob",
  • "category": "incident",
  • "comments": [
    ],
  • "creation_date": "2022-07-21T09:02:40.083388+00:00",
  • "description": "Ticket description",
  • "followers": [
    ],
  • "name": "CS0001401",
  • "onna_parent_id": "da72de92fef04c6a9cc5cfe018fa9cd6",
  • "origin_tags": [
    ],
  • "priority": "medium",
  • "reactions": [
    ],
  • "ref": "f352dc9387632300d6b0a7da0acb0b60",
  • "requester": "Alice",
  • "severity": "low",
  • "status": "open",
  • "subcategory": "hardware",
  • "type": "incident",
  • "update_date": "2022-07-21T09:02:40.083388+00:00",
  • "updater": "Bob",
  • "url": "https://instance.servicenow.com/api/sn_customerservice/case/f352dc9387632300d6b0a7da0acb0b60"
}

Response samples

Content type
application/json
{
  • "onna_id": "string"
}

Delete Ticket

Delete the ticket.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the ticket.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request DELETE 'https://api.onna.com/v1/resources/tickets/tk3f0c5339de42f9964e6afe9bf20358' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Read Ticket

Retrieve a ticket resource.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the ticket.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/resources/tickets/tk3f0c5339de42f9964e6afe9bf20358' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "assignee_group": "IT Support",
  • "assignees": [
    ],
  • "author": "Bob",
  • "category": "incident",
  • "comments": [
    ],
  • "creation_date": "2022-07-21T09:02:40.083388+00:00",
  • "description": "Ticket description",
  • "followers": [
    ],
  • "name": "CS0001401",
  • "onna_parent_id": "da72de92fef04c6a9cc5cfe018fa9cd6",
  • "origin_tags": [
    ],
  • "priority": "medium",
  • "reactions": [
    ],
  • "ref": "f352dc9387632300d6b0a7da0acb0b60",
  • "requester": "Alice",
  • "severity": "low",
  • "status": "open",
  • "subcategory": "hardware",
  • "type": "incident",
  • "update_date": "2022-07-21T09:02:40.083388+00:00",
  • "updater": "Bob",
  • "url": "https://instance.servicenow.com/api/sn_customerservice/case/f352dc9387632300d6b0a7da0acb0b60"
}

Update Ticket

Update a ticket resource.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Ticket ID)

Unique ID of the ticket.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Array of Tags (strings) or Tags (null) (Tags)

List of onna tags to update for the ticket.

Any of
Array
string

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Upload

A generic endpoint to upload a raw file to an existing resource (ticket, file, etc).

Our upload engine is based on the TUS protocol and treats every upload as a resumable file upload.

Check our get started guide.

Whatever the programming language you're using, it's possible that there's a library that integrates this protocol.

For more information about TUS, see the TUS documentation.

Head Resource File Resumable Upload

HEAD a resource's file, for use with the TUS protocol.

Authorizations:
OAuth2
path Parameters
id
required
string (Id)
header Parameters
tus-resumable
string (Tus-Resumable)

The Tus-Resumable header is included in every request and response.

Tus-Resumable: 1.0.0

For more information on the headers used by TUS, see "the protocol specification".

authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl -i 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'HEAD' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'content-type: application/offset+octet-stream' \
  -H 'tus-resumable: 1.0.0' \

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Options Resource File

TUS OPTIONS may be used to gather information about the Server's current configuration.

Authorizations:
OAuth2
path Parameters
id
required
string (Id)
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl -i 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'OPTIONS' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'content-type: application/offset+octet-stream' \

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Resume Resource File Upload

TUS PATCH applies partial modifications to a resource.

Authorizations:
OAuth2
path Parameters
id
required
string (Id)
header Parameters
content-length
string (Content-Length)

The Content-Length header indicates the size of the message body, in bytes, sent to the recipient.

Content-Length: 512

For more information on headers, see "the MDN Web Docs".

content-type
string (Content-Type)

The Content-Type representation header is used to indicate the original media type of the resource (prior to any content encoding applied for sending).

Content-Type: application/json; charset=utf-8

For more information on headers, see "the MDN Web Docs".

upload-offset
string (Upload-Offset)

The Upload-Offset request and response header indicates a byte offset within a resource. The value MUST be a non-negative integer.

Upload-Offset: 64

For more information on the headers used by TUS, see "the protocol specification".

tus-resumable
string (Tus-Resumable)

The Tus-Resumable header is included in every request and response.

Tus-Resumable: 1.0.0

For more information on the headers used by TUS, see "the protocol specification".

authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'PATCH' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'content-type: application/offset+octet-stream' \
  -H 'tus-resumable: 1.0.0' \
  -H 'upload-offset: 0' \
  --data $'%PDF-1.4\v3ryl0ngstr1ng0fR4wD4t4' \
  --compressed

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Create Resource File Resumable Upload

TUS CREATION endpoint.

The created file has the same URL as the current endpoint, since a resource can only have a single file.

Authorizations:
OAuth2
path Parameters
id
required
string (Id)
header Parameters
upload-defer-length
string (Upload-Defer-Length)

The Upload-Defer-Length request and response header indicates that the size of the upload is not known currently and will be transferred later. Its value MUST be 1. If the length of an upload is not deferred, this header MUST be omitted.

Upload-Defer-Length: 1

For more information on the headers used by TUS, see "the protocol specification".

upload-length
string (Upload-Length)

The Upload-Length request and response header indicates the size of the entire upload in bytes. The value MUST be a non-negative integer.

Upload-Length: 512

For more information on the headers used by TUS, see "the protocol specification".

upload-metadata
string (Upload-Metadata)

The Upload-Metadata request and response header MUST consist of one or more comma-separated key-value pairs. The key and value MUST be separated by a space. The key MUST NOT contain spaces and commas and MUST NOT be empty. The key SHOULD be ASCII encoded and the value MUST be Base64 encoded. All keys MUST be unique. The value MAY be empty. In these cases, the space, which would normally separate the key and the value, MAY be left out.

Upload-Metadata: filename d29ybGRfZG9taW5hdGlvbl9wbGFuLnBkZg==,is_confidential

For more information on the headers used by TUS, see "the protocol specification".

tus-resumable
string (Tus-Resumable)

The Tus-Resumable header is included in every request and response.

Tus-Resumable: 1.0.0

For more information on the headers used by TUS, see "the protocol specification".

authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'POST' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'content-length: 0' \
  -H 'tus-resumable: 1.0.0' \
  -H 'upload-length: 44251' \
  -H 'upload-metadata: name Q3JlYXRpdmVjb21tb25zLXdoYXQtaXMtY3JlYXRpdmUtY29tbW9uc19lbmcucGRm' \
  --compressed

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Create Resource File Single Request

Create single request for resource file upload.

Authorizations:
OAuth2
path Parameters
id
required
string (Id)
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl -i 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'PUT' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'content-type: application/offset+octet-stream' \

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Utils

API Utils, such as the health endpoint.

Health Check

Check service status, version and build.

Authorizations:
OAuth2

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/health' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json' \

Response samples

Content type
application/json
{
  • "release_id": "1.0.0",
  • "status": "pass",
  • "version": "v1"
}

Wallet

The Wallet is a store where external credentials are stored in Onna platform. A WalletEntry is an entity that holds a single credential. It can be either a plain string or a JSON object and can store additional metadata as well.

This collection includes all the endpoints that enable you to work.

List Wallets

List wallet entries.

Authorizations:
OAuth2
query Parameters
Cursor (string) or Cursor (null) (Cursor)
Examples: cursor=2022-02-22T11:11:11.12345
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl -X GET "https://api.onna.com/v1/wallets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "cursor": "2022-02-22T11:11:11.12345",
  • "items": [
    ]
}

Create Wallet Entry

Create a wallet entry.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
AllowedCredentialConfigTypes (string) or null
credential_type_name
string (AllowedCredentialTypes)
Default: "ExternalCredential"
Enum: "ExternalCredential" "GSuiteEDatasource" "BoxEDatasource" "SlackEDatasource" "MsTeamsEDatasource" "Datasource"
Credentials (string) or Credentials (object) or Credentials (null) (Credentials)

Credentials to store in the wallet entry.

AllowedCredentialScopesTypes (string) or null
Default: "content.read"
Metadata (object) or Metadata (null) (Metadata)

Metadata associated with the credentials to store.

name
string (Name)
Default: "Public API Wallet Entry"

Display name of the wallet entry.

Responses

Request samples

Content type
application/json
{
  • "credentials": "ASECR3TT0K3N",
  • "metadata": {
    },
  • "name": "wallet1"
}

Response samples

Content type
application/json
{
  • "onna_id": "006334fe06174ccaa2d1710a37e6d7f6"
}

Delete wallet entry

Delete a wallet entry

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the wallet entry.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --location --request DELETE 'https://api.onna.com/v1/wallets/f601fdfadf5c4bea99186f24bc7aa306' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Retrieve wallet entry info

Retrieve information related to a wallet entry.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the wallet entry.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/wallets/f601fdfadf5c4bea99186f24bc7aa306' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json' \

Response samples

Content type
application/json
{
  • "creation_datetime": "2021-08-25T12:00:00Z",
  • "metadata": {
    },
  • "modification_datetime": "2021-08-25T12:00:00Z",
  • "name": "Public API Wallet Entry",
  • "onna_id": "ws6f0c5339de42f9964e6afe9bf20469"
}

Update Wallet Entry

Update the wallet entry. For example, rename it, update the credentials or the metadata.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the wallet entry.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Credentials (string) or Credentials (object) or Credentials (null) (Credentials)

Credentials to store in the wallet entry.

Metadata (object) or Metadata (null) (Metadata)

Metadata associated with the credentials to store.

Name (string) or Name (null) (Name)

Display name of the wallet entry.

Responses

Request samples

Content type
application/json
{
  • "credentials": "NEWASECR3TT0K3N",
  • "metadata": {
    },
  • "name": "Updated wallet entry"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Search

POST /search sends the same JSON body the Onna UI posts to @frontsearch.

Request fields

Field Required Notes
advanced yes JSON-logic query tree (and, or, and_not, conditions)
from no Offset. Default UI behavior starts at 0.
size no Page size (0 = counts/aggregations only). Max 1000.
includes no Fields to return on each result
facets no UI-style filters (facetType + facetsSelected)
sort no {"field": "date_created", "direction": "desc"}
type no Defaults to SYS_ED (UI system search). Use USR_ED for user searches.
query no Display string for the search terms
hide_children no Exclude child resources
highlight no Return hit highlights
aggs_includes no Aggregation fields to compute

advanced must include a logical operator at its root. Invalid advanced or size returns 422.

Typical request

{
  "advanced": {
    "and": [
      {"text_contains": [{"var": "extracted_text"}, "contract"]},
      {">=": [{"var": "date_created"}, "2024-01-01"]},
      {"<=": [{"var": "date_created"}, "2024-12-31"]}
    ]
  },
  "from": 0,
  "size": 50,
  "includes": ["@uid", "title", "date_created"],
  "facets": [{"facetType": "workspaces", "facetsSelected": ["ws-uuid-1"]}],
  "type": "SYS_ED",
  "query": "contract"
}

Common advanced conditions

Goal Condition
Keywords {"text_contains": [{"var": "extracted_text"}, "term"]}
Multiple keywords Add one text_contains per term inside and (all match) or or (any match)
Date from {">=": [{"var": "date_created"}, "2024-01-01"]}
Date to {"<=": [{"var": "date_created"}, "2024-12-31"]}
Field in list {"in": [{"var": "parent_datasource.uuid"}, ["ds-1"]]}
Field exists {"exists": [{"var": "title"}]}

Use facets for workspace, datasource, user, and tag filters — same as the UI filter panel. Use in / not_in inside advanced when you need explicit field matching in the query tree.

Paginate with from + size. Dates use YYYY-MM-DD.

Search

Search preserved content by proxying a frontsearch query to canonical.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
advanced
required
object (Advanced)

JSON-logic query tree

Array of Aggs Includes (strings) or Aggs Includes (null) (Aggs Includes)

Aggregation fields to include

Array of Facets (objects) or Facets (null) (Facets)

UI filters, e.g. {"facetType": "workspaces", "facetsSelected": ["uuid"]}

From (integer) or From (null) (From)

Result offset for pagination

Hide Children (boolean) or Hide Children (null) (Hide Children)

Exclude child resources when true

Highlight (boolean) or Highlight (null) (Highlight)

Request hit highlighting in list view

Array of Includes (strings) or Includes (null) (Includes)

Resource fields to return

Query (string) or Query (null) (Query)

Human-readable query string (optional metadata)

Size (integer) or Size (null) (Size)

Page size. Use 0 to fetch counts/aggregations only.

Sort (object) or Sort (null) (Sort)

Sort, e.g. {"field": "date_created", "direction": "desc"}

type
string (Type)
Default: "SYS_ED"

Query origin. UI default is "SYS_ED". Use "USR_ED" for user-initiated searches.

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "advanced": {
    },
  • "facets": [
    ],
  • "from": 0,
  • "includes": [
    ],
  • "query": "contract",
  • "size": 50,
  • "type": "SYS_ED"
}

Response samples

Content type
application/json
{
  • "aggregations": { },
  • "items_count": 1,
  • "member": [
    ],
  • "search_id": "search-abc123"
}

Exports

Exports are a collection of files from either a search or a datasource, based on the settings configured.

Exports can include additional metadata, related files, natives, PDFs, or extracted text in downloadable zip(s) that can be used to provide information for an interested party.

The endpoints in this section allow you to list exports, retrieve information about a specific export, and download export metadata.

An export response includes information such as its status, name, size, and the number of documents processed. The metadata URL provides access to additional information related to the export.

NOTE:
When downloading export volumes, the generated metadata.csv/dat file will always be in the last volume generated.

List Exports

List exports.

Authorizations:
OAuth2
query Parameters
Cursor (string) or Cursor (null) (Cursor)
Examples: cursor=2022-02-22T11:11:11.12345
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/exports' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{}

Retrieve export info

Retrieve information related to an Export.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the Export.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/exports/fs3f0c5339de42f9964e6afe9bf20169' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{}

Download export metadata

Download the metadata of an Export.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (ID)

Unique ID of the Export.

query Parameters
key
required
string (Key)

Temporary key to download the metadata.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/exports/fs3f0c5339de42f9964e6afe9bf20169/metadata?key=R9OXYeXjSiLT3oLSxfs5H6HhhmBnd' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
null

Legal Hold

Microsoft In-Place Preservation (IPP)

Reference for setting up, operating, and troubleshooting integrated legal holds against Microsoft 365 through the legal-hold-service REST API.

At a glance

Microsoft IPP places in-place legal holds on Microsoft 365 content so it cannot be permanently deleted while a matter is active. It is implemented on top of Microsoft Purview eDiscovery (Premium) via the Microsoft Graph security API.

What gets held, by sync option:

Sync option Source What is preserved
mailbox Exchange Online mailbox The custodian's mailbox (inbox, sent, deleted)
site User's personal SharePoint site OneDrive content
teams Teams group mailbox + SharePoint Channel messages and Teams-backed files

If no sync option is supplied on the source, all three are applied by default.

Prerequisites

Microsoft 365 tenant

  1. Purview eDiscovery (Premium) licensing — the holds API is a Premium feature.
  2. A delegated OAuth user with eDiscovery permissions to create cases, legal holds, and user/site sources. Minimum useful Graph scopes:
    • eDiscovery.ReadWrite.All — create cases, policies, holds, sources.
    • Directory/User read sufficient to enumerate mailboxes, OneDrive, Teams, and groups for the custodians on hold.

Onna credential

  1. Create an authorized connection through the "Grant Access to Microsoft eDiscovery (Premium)" OAuth flow (Onna UI → @@authorized-connections → Integrated Legal Holds).
  2. The credential must be stored with credentials_scopes_type = preservation. Anything else is rejected at POST /sources with a 412.
  3. POST /sources verifies the credential live by calling Purview GET /security/cases/ediscoveryCases. Any failure surfaces as 412 Invalid credential: <reason>.

How a hold maps onto Purview

When you place a Microsoft hold, this structure is created in the customer's tenant:

ediscoveryCase                  ← container ("slot"); one or more per Onna source
 └── legalHold (policy)         ← where sources attach, holds the content query
      ├── userSource (mailbox)  ← per custodian: mailbox + Teams group mailboxes
      └── siteSource (site)     ← per custodian: OneDrive + Teams SharePoint sites
 └── custodian                  ← registered on the case (not the policy)

Naming

  • Case: Reveal::<sanitized matter title>::<last 4 of source id>::<index>
  • Policy: Reveal::<sanitized matter title>::<last 4 of source id>

If Purview returns a 409 on a duplicate name (case-insensitive collision), the service retries with a disambiguated name.

Auto-sharding

A single case/policy is capped at 1000 custodians. When a slot fills, the service auto-creates a new case + policy and continues placing holds. Consequence: a single Onna source with thousands of custodians fans out to multiple Purview cases — expect to see several cases in the Purview portal for large matters. This is by design.

Setting up a hold

The end-to-end flow is four calls, in order. The fourth is what actually places the holds in Microsoft 365 — the first three only set up the data model in Onna.

# Call What it does
1 POST /matters Creates the matter; returns matter_id for later calls.
2 POST /matters/{matter_id}/custodians Adds custodians (up to 5000). Unresolved emails are not rejected here.
3 POST /matters/{matter_id}/sources Adds Microsoft source (config_type: office365) with sync options and credential.
4 POST /matters/{matter_id}/sources/{source_id}/custodians Assigns custodians (triggers placement). Use custodian_ids or all_custodians: true.

Schemas, full payloads, and response shapes for each call are on their endpoint pages.

Things that aren't obvious from the endpoint schemas

  • Step 4 is the trigger. Steps 1–3 are setup; nothing reaches Microsoft until step 4.
  • update_holds on step 4 defaults to true, which schedules placement immediately. Set update_holds=false to stage the assignment without running placement, then PATCH /sources/{source_id} with status.status = "scheduled" to kick it off later.
  • Sync options are immutable once a source exists. PATCH /sources/{id} returns 412 Sync options can not be modified! if you try to change them. To change the option set, delete the source and re-create it (only possible if no holds are placed yet).
  • start_date / end_date on the source are optional content-date filters. null means "no date filter."
  • Default sync options. Omit sync_options entirely and the service applies all three of mailbox, site, teams. Provide an explicit list to opt out of any of them.

Monitoring the hold

Source detail

GET /matters/{matter_id}/sources/{source_id} — returns the source plus a breakdown of custodians by status. Poll this to watch progress.

Custodian list

GET /matters/{matter_id}/sources/{source_id}/custodians?status=error&limit=100 — filterable by custodian status; per-custodian error reason is included.

Custodian CSV report

GET /matters/{matter_id}/sources/{source_id}/csv — available once the source reaches successful, released, or error. One row per custodian: name, email, role, found-in-M365, on-hold, hold date.

What "done" means

A source moves to successful once every Purview hold under it reports applied or partial.

  • applied → fully held → custodian successful.
  • partial → some sub-targets held, some didn't (typical: mailbox held, OneDrive missing) → custodian partial.
  • Anything else → still updating.

partial is a confirmed status, not an error. The service treats it as a successful confirmation: the source itself still moves to successful, but the affected custodians land in partial. Check the per-custodian error field to see which sub-target (typically OneDrive or Teams) failed.

Progress is persisted after every batch, so a workflow that's interrupted and retries is idempotent — it won't double-place or double-count.

Releasing a hold

Three release granularities:

Action Endpoint
Release specific custodians POST /matters/{matter_id}/sources/{source_id}/custodians/release
Release one whole source POST /matters/{matter_id}/sources/{source_id}/release
Release every source in the matter POST /matters/{matter_id}/sources/release

What release does:

  1. Removes the per-custodian userSource / siteSource entries from the Purview policy.
  2. Once a policy has no remaining sources, the policy is deleted.
  3. Once a case has no remaining policies, the case is deleted.

Important behaviors:

  • Onna deletes the Purview case at the end of a release instead of closing it. The Purview close-case endpoint is unreliable (frequent 500s/timeouts), so Onna does not use it. You will not see a "Closed" case in the Purview portal for matters released through Onna — the case is gone.
  • A source with active holds cannot be deleted — DELETE /sources/{id} returns 412 Unable to delete source that has active holds. Release first.
  • A matter cannot be deleted while it still has active source holds.

Operational notes

Behaviors any integrator will observe. Most are dictated by Purview, not by us.

Inactive mailboxes appear with a leading dot

Exchange requires inactive mailboxes to be addressed as .user@tenant.com. The service probes the user's mailbox first to decide which form to send. You will see the dotted form in the Purview portal for any inactive custodian — this is expected, not an error.

Custodians not in Microsoft 365 are skipped, not retried

A custodian whose email doesn't resolve in Microsoft 365 is marked not_found and skipped. They are not retried in subsequent runs. To re-attempt, release the custodian and re-add them.

OneDrive must be provisioned to be held

If a custodian has never signed into OneDrive, their personal site has no webUrl and the OneDrive portion of the hold cannot be placed. The mailbox is still held, but the custodian lands in partial. The error appears at the source level as "N OneDrive sites could not be held".

The fix: provision OneDrive for that custodian on the Microsoft side (sign in once, or use the SharePoint admin pre-provisioning tooling), then release and re-add the custodian.

Teams holds are best-effort and asynchronous

Teams are shared resources, so they are held at the policy level (not per custodian) and placed in a second pass after the per-custodian mailbox/site holds settle.

  • Each Team is retried up to 3 times before being marked failed on the source.
  • A failing Team does not fail the whole source — mailbox and OneDrive holds still apply.
  • Teams are reference-counted: the underlying Team source is only released when the last custodian member of that Team is released.
  • If a custodian's joined-Teams list cannot be enumerated, unresolved Teams are skipped and logged; the rest proceed.

Throughput

  • Up to 10 concurrent Graph calls per client (per source).
  • Custodians processed in batches of 100.
  • Transient errors — including 401 after a token refresh — are retried with exponential backoff before failing the custodian.

Troubleshooting

Symptom Cause and fix
POST /sources → 412 Credential not configured with legal hold scopes Wallet not preservation. Re-run eDiscovery (Premium) OAuth under @@authorized-connections.
POST /sources → 412 Invalid credential: <reason> Purview probe failed: missing scopes or permissions. Re-issue the credential.
Custodian not_found Email not in M365. Confirm address; release and re-add to retry.
Custodian partial Mailbox held; OneDrive/Teams failed. Often unprovisioned OneDrive — fix, then re-place.
"N OneDrive sites could not be held" Provision OneDrive for those users, then re-run.
"N Teams channels could not be held" Teams pass failed after retries; mailbox holds remain.
"Insufficient permissions to place hold..." 401/403 on Graph. Re-run OAuth with eDiscovery scopes.
Source stuck in updating Holds still propagating. Wait; then check per-custodian errors.
Multiple Purview cases per matter Expected above 1000 custodians per slot (auto-sharding).
DELETE /sources/{id} → 412 active holds Release holds on the source first.
No "Closed" case in Purview after release Expected — Onna deletes the case instead of closing it.

Where to look for details

  • Per-custodian errors are returned in the custodian list response (error_info on each custodian). Filter status=error or status=partial to find them.
  • Source-level errors are aggregated on the source response (status.error_info).
  • Per-hold errors (one entry per Purview policy under the source) are exposed inside the source's external_holds map and cleared automatically once the affected sub-target succeeds.

Status values

Source statuses

pending → scheduled → updating → successful
                                     ↓
                              pending_release → updating_release → released

Plus terminal/error states: error, not_found, pending_remove, removed.

Status Meaning
pending Source created, no custodians assigned yet.
scheduled Workflow scheduled, hasn't started.
updating Placement in progress.
successful All custodian holds confirmed (applied or partial).
error Placement finished with at least one source-level failure.
not_found Source data was not found at the provider.
pending_release Release scheduled.
updating_release Release in progress.
released All holds removed; Purview case deleted.
pending_remove Source scheduled for removal from Onna after release.
removed Fully removed.

Per-custodian statuses

Status Meaning
pending Not yet processed.
updating Placement in progress.
successful All configured sync options held.
partial Some sync options held, others failed (e.g. no OneDrive).
error All hold targets failed; reason in the per-custodian error field.
not_found Custodian doesn't exist in Microsoft 365 — skipped, not retried.
pending_release Release scheduled for this custodian.
released Hold removed.
pending_remove / removed Lifecycle after release.

Cheat sheet

Need Value
config_type for Microsoft 365 office365
Required credential scope preservation
Custodians per Purview case 1000 (auto-sharded above this)
Default sync options when omitted mailbox + site + teams
Confirmed Purview hold statuses applied, partial

External reference: Microsoft Purview eDiscovery (Premium) limits.

Microsoft In-Place Preservation (IPP)

Reference for setting up, operating, and troubleshooting integrated legal holds against Microsoft 365 through the legal-hold-service REST API.

At a glance

Microsoft IPP places in-place legal holds on Microsoft 365 content so it cannot be permanently deleted while a matter is active. It is implemented on top of Microsoft Purview eDiscovery (Premium) via the Microsoft Graph security API.

What gets held, by sync option:

Sync option Source What is preserved
mailbox Exchange Online mailbox The custodian's mailbox (inbox, sent, deleted)
site User's personal SharePoint site OneDrive content
teams Teams group mailbox + SharePoint Channel messages and Teams-backed files

If no sync option is supplied on the source, all three are applied by default.

Prerequisites

Microsoft 365 tenant

  1. Purview eDiscovery (Premium) licensing — the holds API is a Premium feature.
  2. A delegated OAuth user with eDiscovery permissions to create cases, legal holds, and user/site sources. Minimum useful Graph scopes:
    • eDiscovery.ReadWrite.All — create cases, policies, holds, sources.
    • Directory/User read sufficient to enumerate mailboxes, OneDrive, Teams, and groups for the custodians on hold.

Onna credential

  1. Create an authorized connection through the "Grant Access to Microsoft eDiscovery (Premium)" OAuth flow (Onna UI → @@authorized-connections → Integrated Legal Holds).
  2. The credential must be stored with credentials_scopes_type = preservation. Anything else is rejected at POST /sources with a 412.
  3. POST /sources verifies the credential live by calling Purview GET /security/cases/ediscoveryCases. Any failure surfaces as 412 Invalid credential: <reason>.

How a hold maps onto Purview

When you place a Microsoft hold, this structure is created in the customer's tenant:

ediscoveryCase                  ← container ("slot"); one or more per Onna source
 └── legalHold (policy)         ← where sources attach, holds the content query
      ├── userSource (mailbox)  ← per custodian: mailbox + Teams group mailboxes
      └── siteSource (site)     ← per custodian: OneDrive + Teams SharePoint sites
 └── custodian                  ← registered on the case (not the policy)

Naming

  • Case: Reveal::<sanitized matter title>::<last 4 of source id>::<index>
  • Policy: Reveal::<sanitized matter title>::<last 4 of source id>

If Purview returns a 409 on a duplicate name (case-insensitive collision), the service retries with a disambiguated name.

Auto-sharding

A single case/policy is capped at 1000 custodians. When a slot fills, the service auto-creates a new case + policy and continues placing holds. Consequence: a single Onna source with thousands of custodians fans out to multiple Purview cases — expect to see several cases in the Purview portal for large matters. This is by design.

Setting up a hold

The end-to-end flow is four calls, in order. The fourth is what actually places the holds in Microsoft 365 — the first three only set up the data model in Onna.

# Call What it does
1 POST /matters Creates the matter; returns matter_id for later calls.
2 POST /matters/{matter_id}/custodians Adds custodians (up to 5000). Unresolved emails are not rejected here.
3 POST /matters/{matter_id}/sources Adds Microsoft source (config_type: office365) with sync options and credential.
4 POST /matters/{matter_id}/sources/{source_id}/custodians Assigns custodians (triggers placement). Use custodian_ids or all_custodians: true.

Schemas, full payloads, and response shapes for each call are on their endpoint pages.

Things that aren't obvious from the endpoint schemas

  • Step 4 is the trigger. Steps 1–3 are setup; nothing reaches Microsoft until step 4.
  • update_holds on step 4 defaults to true, which schedules placement immediately. Set update_holds=false to stage the assignment without running placement, then PATCH /sources/{source_id} with status.status = "scheduled" to kick it off later.
  • Sync options are immutable once a source exists. PATCH /sources/{id} returns 412 Sync options can not be modified! if you try to change them. To change the option set, delete the source and re-create it (only possible if no holds are placed yet).
  • start_date / end_date on the source are optional content-date filters. null means "no date filter."
  • Default sync options. Omit sync_options entirely and the service applies all three of mailbox, site, teams. Provide an explicit list to opt out of any of them.

Monitoring the hold

Source detail

GET /matters/{matter_id}/sources/{source_id} — returns the source plus a breakdown of custodians by status. Poll this to watch progress.

Custodian list

GET /matters/{matter_id}/sources/{source_id}/custodians?status=error&limit=100 — filterable by custodian status; per-custodian error reason is included.

Custodian CSV report

GET /matters/{matter_id}/sources/{source_id}/csv — available once the source reaches successful, released, or error. One row per custodian: name, email, role, found-in-M365, on-hold, hold date.

What "done" means

A source moves to successful once every Purview hold under it reports applied or partial.

  • applied → fully held → custodian successful.
  • partial → some sub-targets held, some didn't (typical: mailbox held, OneDrive missing) → custodian partial.
  • Anything else → still updating.

partial is a confirmed status, not an error. The service treats it as a successful confirmation: the source itself still moves to successful, but the affected custodians land in partial. Check the per-custodian error field to see which sub-target (typically OneDrive or Teams) failed.

Progress is persisted after every batch, so a workflow that's interrupted and retries is idempotent — it won't double-place or double-count.

Releasing a hold

Three release granularities:

Action Endpoint
Release specific custodians POST /matters/{matter_id}/sources/{source_id}/custodians/release
Release one whole source POST /matters/{matter_id}/sources/{source_id}/release
Release every source in the matter POST /matters/{matter_id}/sources/release

What release does:

  1. Removes the per-custodian userSource / siteSource entries from the Purview policy.
  2. Once a policy has no remaining sources, the policy is deleted.
  3. Once a case has no remaining policies, the case is deleted.

Important behaviors:

  • Onna deletes the Purview case at the end of a release instead of closing it. The Purview close-case endpoint is unreliable (frequent 500s/timeouts), so Onna does not use it. You will not see a "Closed" case in the Purview portal for matters released through Onna — the case is gone.
  • A source with active holds cannot be deleted — DELETE /sources/{id} returns 412 Unable to delete source that has active holds. Release first.
  • A matter cannot be deleted while it still has active source holds.

Operational notes

Behaviors any integrator will observe. Most are dictated by Purview, not by us.

Inactive mailboxes appear with a leading dot

Exchange requires inactive mailboxes to be addressed as .user@tenant.com. The service probes the user's mailbox first to decide which form to send. You will see the dotted form in the Purview portal for any inactive custodian — this is expected, not an error.

Custodians not in Microsoft 365 are skipped, not retried

A custodian whose email doesn't resolve in Microsoft 365 is marked not_found and skipped. They are not retried in subsequent runs. To re-attempt, release the custodian and re-add them.

OneDrive must be provisioned to be held

If a custodian has never signed into OneDrive, their personal site has no webUrl and the OneDrive portion of the hold cannot be placed. The mailbox is still held, but the custodian lands in partial. The error appears at the source level as "N OneDrive sites could not be held".

The fix: provision OneDrive for that custodian on the Microsoft side (sign in once, or use the SharePoint admin pre-provisioning tooling), then release and re-add the custodian.

Teams holds are best-effort and asynchronous

Teams are shared resources, so they are held at the policy level (not per custodian) and placed in a second pass after the per-custodian mailbox/site holds settle.

  • Each Team is retried up to 3 times before being marked failed on the source.
  • A failing Team does not fail the whole source — mailbox and OneDrive holds still apply.
  • Teams are reference-counted: the underlying Team source is only released when the last custodian member of that Team is released.
  • If a custodian's joined-Teams list cannot be enumerated, unresolved Teams are skipped and logged; the rest proceed.

Throughput

  • Up to 10 concurrent Graph calls per client (per source).
  • Custodians processed in batches of 100.
  • Transient errors — including 401 after a token refresh — are retried with exponential backoff before failing the custodian.

Troubleshooting

Symptom Cause and fix
POST /sources → 412 Credential not configured with legal hold scopes Wallet not preservation. Re-run eDiscovery (Premium) OAuth under @@authorized-connections.
POST /sources → 412 Invalid credential: <reason> Purview probe failed: missing scopes or permissions. Re-issue the credential.
Custodian not_found Email not in M365. Confirm address; release and re-add to retry.
Custodian partial Mailbox held; OneDrive/Teams failed. Often unprovisioned OneDrive — fix, then re-place.
"N OneDrive sites could not be held" Provision OneDrive for those users, then re-run.
"N Teams channels could not be held" Teams pass failed after retries; mailbox holds remain.
"Insufficient permissions to place hold..." 401/403 on Graph. Re-run OAuth with eDiscovery scopes.
Source stuck in updating Holds still propagating. Wait; then check per-custodian errors.
Multiple Purview cases per matter Expected above 1000 custodians per slot (auto-sharding).
DELETE /sources/{id} → 412 active holds Release holds on the source first.
No "Closed" case in Purview after release Expected — Onna deletes the case instead of closing it.

Where to look for details

  • Per-custodian errors are returned in the custodian list response (error_info on each custodian). Filter status=error or status=partial to find them.
  • Source-level errors are aggregated on the source response (status.error_info).
  • Per-hold errors (one entry per Purview policy under the source) are exposed inside the source's external_holds map and cleared automatically once the affected sub-target succeeds.

Status values

Source statuses

pending → scheduled → updating → successful
                                     ↓
                              pending_release → updating_release → released

Plus terminal/error states: error, not_found, pending_remove, removed.

Status Meaning
pending Source created, no custodians assigned yet.
scheduled Workflow scheduled, hasn't started.
updating Placement in progress.
successful All custodian holds confirmed (applied or partial).
error Placement finished with at least one source-level failure.
not_found Source data was not found at the provider.
pending_release Release scheduled.
updating_release Release in progress.
released All holds removed; Purview case deleted.
pending_remove Source scheduled for removal from Onna after release.
removed Fully removed.

Per-custodian statuses

Status Meaning
pending Not yet processed.
updating Placement in progress.
successful All configured sync options held.
partial Some sync options held, others failed (e.g. no OneDrive).
error All hold targets failed; reason in the per-custodian error field.
not_found Custodian doesn't exist in Microsoft 365 — skipped, not retried.
pending_release Release scheduled for this custodian.
released Hold removed.
pending_remove / removed Lifecycle after release.

Cheat sheet

Need Value
config_type for Microsoft 365 office365
Required credential scope preservation
Custodians per Purview case 1000 (auto-sharded above this)
Default sync options when omitted mailbox + site + teams
Confirmed Purview hold statuses applied, partial

External reference: Microsoft Purview eDiscovery (Premium) limits.

Acknowledge an email notification

Authorizations:
OAuth2
Request Body schema: application/json
token
required
string (Token)

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
null

Delete account logo

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
null

Get account logo

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "file": "string",
  • "filename": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "type": "none"
}

Update account logo

Authorizations:
OAuth2
Request Body schema: application/json
File (string) or File (null) (File)
Filename (string) or Filename (null) (Filename)
type
string (LegalHold_LogoTypes)
Default: "onna"
Enum: "none" "onna" "custom"

Responses

Request samples

Content type
application/json
{
  • "file": "string",
  • "filename": "string",
  • "type": "none"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "file": "string",
  • "filename": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "type": "none"
}

Get a list of the matters

Authorizations:
OAuth2
query Parameters
Since (string) or Since (null) (Since)

Responses

Response samples

Content type
application/json
{ }

Add a matter

Authorizations:
OAuth2
Request Body schema: application/json
Billing Number (string) or Billing Number (null) (Billing Number)
Case Owner (string) or Case Owner (null) (Case Owner)
Jurisdiction (string) or Jurisdiction (null) (Jurisdiction)
MatterStatus (string) or null
Default: "active"
MatterTypes (string) or null
Notes (string) or Notes (null) (Notes)
Title (string) or Title (null) (Title)

Responses

Request samples

Content type
application/json
{
  • "billing_number": "string",
  • "case_owner": "string",
  • "jurisdiction": "string",
  • "matter_status": "active",
  • "matter_type": "litigation",
  • "notes": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{ }

Delete a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)

Responses

Response samples

Content type
application/json
{ }

Update a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
Request Body schema: application/json
Billing Number (string) or Billing Number (null) (Billing Number)
Case Owner (string) or Case Owner (null) (Case Owner)
Jurisdiction (string) or Jurisdiction (null) (Jurisdiction)
MatterStatus (string) or null
Default: "active"
MatterTypes (string) or null
Notes (string) or Notes (null) (Notes)
Title (string) or Title (null) (Title)

Responses

Request samples

Content type
application/json
{
  • "billing_number": "string",
  • "case_owner": "string",
  • "jurisdiction": "string",
  • "matter_status": "active",
  • "matter_type": "litigation",
  • "notes": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{ }

Close a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{ }

Get a list of the custodians

Parameters:

  • sort: Sort the result by field
  • order: Sort the result in acs or desc
  • limit: The max number of items to be returned, default is 10, and maximum is 100
  • cursor: Get next custodians from a cursor
Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Notification Id (string) or Notification Id (null) (Notification Id)
Ack (boolean) or Ack (null) (Ack)
Sent (boolean) or Sent (null) (Sent)
Search (string) or Search (null) (Search)
On Hold (boolean) or On Hold (null) (On Hold)
Role (string) or Role (null) (Role)
NotificationType (string) or Notification Type (null) (Notification Type)
Default: "initial"
sort
string (LegalHold_legal_hold_service__rest__custodians__Sort)
Default: "name"
Enum: "name" "role" "initial_notice_sent_on" "acknowledged_at" "sources"
order
string (LegalHold_Order)
Default: "asc"
Enum: "asc" "desc"
limit
integer (Limit) [ 0 .. 100 ]
Default: 10
Cursor (string) or Cursor (null) (Cursor)
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "custodians": [ ],
  • "total_count": 0
}

Add a custodian

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
required
Array of objects (Custodians) [ 1 .. 5000 ] items
Array ([ 1 .. 5000 ] items)
email
required
string (Email) <= 64 characters
first_name
required
string (First Name) <= 40 characters
last_name
required
string (Last Name) <= 40 characters
role
string (LegalHold_Role)
Default: "custodian"
Enum: "custodian" "silent"

Responses

Request samples

Content type
application/json
{
  • "custodians": [
    ]
}

Response samples

Content type
application/json
{
  • "conflict_emails": [
    ],
  • "custodians": [
    ]
}

Delete one or more custodians that are not part of an active hold.

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
All Custodians (boolean) or All Custodians (null) (All Custodians)
Default: false
Array of Custodian Ids (strings) or Custodian Ids (null) (Custodian Ids)

Responses

Request samples

Content type
application/json
{
  • "all_custodians": false,
  • "custodian_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "num_deleted": 0
}

Get a custodian

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
id
required
string (Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "email": "string",
  • "email_activity": [
    ],
  • "first_name": "string",
  • "id": "string",
  • "last_name": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "role": "custodian",
  • "sources": [
    ]
}

Update a custodian

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
id
required
string (Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
role
required
string (LegalHold_Role)
Enum: "custodian" "silent"

Responses

Request samples

Content type
application/json
{
  • "role": "custodian"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "email": "string",
  • "first_name": "string",
  • "id": "string",
  • "last_name": "string",
  • "matter_id": "string",
  • "role": "custodian"
}

Get a list of the notifications

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "notifications": [ ]
}

Add a notification

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
email_bcc
Array of strings (Email Bcc)
Default: []
email_cc
Array of strings (Email Cc)
Default: []
email_content
required
string (Email Content)
email_subject
required
string (Email Subject)
Frequency (integer) or Frequency (null) (Frequency)
type
required
string (LegalHold_NotificationType)
Enum: "initial" "reminder" "ack-reminder" "release"

Responses

Request samples

Content type
application/json
{
  • "email_bcc": [ ],
  • "email_cc": [ ],
  • "email_content": "string",
  • "email_subject": "string",
  • "frequency": 0,
  • "type": "initial"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "email_bcc": [ ],
  • "email_cc": [ ],
  • "email_content": "string",
  • "email_subject": "string",
  • "frequency": 0,
  • "id": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "type": "initial"
}

Delete a notification

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
id
required
string (Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
null

Get a notification

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
id
required
string (Id)
query Parameters
Preview (boolean) or Preview (null) (Preview)
Default: false
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "email_bcc": [ ],
  • "email_cc": [ ],
  • "email_content": "string",
  • "email_subject": "string",
  • "frequency": 0,
  • "id": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "type": "initial"
}

Modify a notification

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
id
required
string (Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
Array of Email Bcc (strings) or Email Bcc (null) (Email Bcc)
Array of Email Cc (strings) or Email Cc (null) (Email Cc)
Email Content (string) or Email Content (null) (Email Content)
Email Subject (string) or Email Subject (null) (Email Subject)
Frequency (integer) or Frequency (null) (Frequency)

Responses

Request samples

Content type
application/json
{
  • "email_bcc": [
    ],
  • "email_cc": [
    ],
  • "email_content": "string",
  • "email_subject": "string",
  • "frequency": 0
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "email_bcc": [ ],
  • "email_cc": [ ],
  • "email_content": "string",
  • "email_subject": "string",
  • "frequency": 0,
  • "id": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "type": "initial"
}

Notify custodians

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
notification_id
required
string (Notification Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
all_custodians
boolean (All Custodians)
Default: false
Array of Custodians (strings) or Custodians (null) (Custodians)

Responses

Request samples

Content type
application/json
{
  • "all_custodians": false,
  • "custodians": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "added_custodians": 0
}

Get a matter sharing

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)

Responses

Response samples

Content type
application/json
{ }

Share a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
Request Body schema: application/json
required
Array of objects (Prinrole)
Array
principal
required
string (Principal)
role
required
string (Role)
setting
required
string (Setting)

Responses

Request samples

Content type
application/json
{
  • "prinrole": [
    ]
}

Response samples

Content type
application/json
null

Get list of sources for a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
order
string (LegalHold_Order)
Default: "asc"
Enum: "asc" "desc"
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "sources": [
    ]
}

Add a new source hold to a matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
config_type
required
string (LegalHold_SourceConfigType)
Enum: "gsuite" "eslack" "ebox" "miro" "office365" "zoom"
credential_id
required
string (Credential Id)
End Date (string) or End Date (null) (End Date)
Start Date (string) or Start Date (null) (Start Date)
object (LegalHold_SourceStatus)
Default: {"progress":{"processed":0,"retry_after":0,"retry_count":0,"total":0},"requires_rerun":false,"status":"pending"}
required
Array of objects (Sync Options)

Responses

Request samples

Content type
application/json
{
  • "config_type": "gsuite",
  • "credential_id": "string",
  • "end_date": "2019-08-24T14:15:22Z",
  • "start_date": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "sync_options": [
    ]
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "config_type": "gsuite",
  • "created_by": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "credential_email": "string",
  • "credential_id": "string",
  • "custodians_not_found": 0,
  • "custodians_on_hold": 0,
  • "deleted": false,
  • "end_date": "2019-08-24T14:15:22Z",
  • "external_holds": { },
  • "id": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "start_date": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "sync_options": [
    ]
}

Release all source holds for a given matter

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
null

Delete a source hold

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
null

Get a source hold by id

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "config_type": "gsuite",
  • "created_by": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "credential_email": "string",
  • "credential_id": "string",
  • "custodians_not_found": 0,
  • "custodians_on_hold": 0,
  • "deleted": false,
  • "end_date": "2019-08-24T14:15:22Z",
  • "error": 0,
  • "external_holds": { },
  • "id": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "num_custodians": 0,
  • "pending": 0,
  • "pending_release": 0,
  • "pending_remove": 0,
  • "released": 0,
  • "removed": 0,
  • "start_date": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "successful": 0,
  • "sync_options": [
    ],
  • "updating": 0
}

Modify an existing source hold

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
Credential Id (string) or Credential Id (null) (Credential Id)
External Holds (object) or External Holds (null) (External Holds)
SourceStatus (object) or null

Responses

Request samples

Content type
application/json
{
  • "credential_id": "string",
  • "external_holds": {
    },
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "config_type": "gsuite",
  • "created_by": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "credential_email": "string",
  • "credential_id": "string",
  • "custodians_not_found": 0,
  • "custodians_on_hold": 0,
  • "deleted": false,
  • "end_date": "2019-08-24T14:15:22Z",
  • "external_holds": { },
  • "id": "string",
  • "matter_id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "start_date": "2019-08-24T14:15:22Z",
  • "status": {
    },
  • "sync_options": [
    ]
}

Get source hold custodians in CSV format

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
null

Get a list of the custodians

Parameters:

  • sort: Sort the result by field
  • order: Sort the result in acs or desc
  • limit: The max number of items to be returned, default is 10, and maximum is 100
  • cursor: Get next custodians from a cursor
Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
CustodianStatus (string) or Status (null) (Status)
sort
string (LegalHold_legal_hold_service__rest__sources__Sort)
Default: "name"
Enum: "name" "creation_date" "modification_date"
order
string (LegalHold_Order)
Default: "asc"
Enum: "asc" "desc"
limit
integer (Limit) [ 0 .. 100 ]
Default: 10
Cursor (string) or Cursor (null) (Cursor)
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
{
  • "cursor": "string",
  • "custodians": [ ],
  • "total_count": 0
}

Assign custodians to a source hold

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Update Holds (boolean) or Update Holds (null) (Update Holds)
Default: true
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
All Custodians (boolean) or All Custodians (null) (All Custodians)
Default: false
Array of Custodian Ids (strings) or Custodian Ids (null) (Custodian Ids)

Responses

Request samples

Content type
application/json
{
  • "all_custodians": false,
  • "custodian_ids": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "custodians": [
    ],
  • "not_added": [ ]
}

Release specific custodians from a source hold

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Permission (string) or Permission (null) (Permission)
Request Body schema: application/json
Array of Custodian Ids (strings) or Custodian Ids (null) (Custodian Ids)
Any of
Array
string

Responses

Request samples

Content type
application/json
{
  • "custodian_ids": [
    ]
}

Response samples

Content type
application/json
null

Release all In Place Preservation configs for a given In Place Preservation

Authorizations:
OAuth2
path Parameters
matter_id
required
string (Matter Id)
source_id
required
string (Source Id)
query Parameters
Permission (string) or Permission (null) (Permission)

Responses

Response samples

Content type
application/json
null

Get Metrics

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
null

Get all templates

Authorizations:
OAuth2
query Parameters
NotificationType (string) or Type (null) (Type)
NotificationTemplateSortField (string) or Sort (null) (Sort)
Default: "name"
Order (string) or Order (null) (Order)
Default: "asc"

Responses

Response samples

Content type
application/json
{
  • "templates": [
    ]
}

Create a new template

Authorizations:
OAuth2
Request Body schema: application/json
email_content
required
string (Email Content)
email_subject
required
string (Email Subject)
name
required
string (Name)
type
required
string (LegalHold_NotificationType)
Enum: "initial" "reminder" "ack-reminder" "release"

Responses

Request samples

Content type
application/json
{
  • "email_content": "string",
  • "email_subject": "string",
  • "name": "string",
  • "type": "initial"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "email_content": "string",
  • "email_subject": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "type": "initial"
}

Delete a template

Authorizations:
OAuth2
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
null

Get a single notification template

Authorizations:
OAuth2
path Parameters
template_id
required
string (Template Id)

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "email_content": "string",
  • "email_subject": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "type": "initial"
}

Modify an existing template

Authorizations:
OAuth2
path Parameters
template_id
required
string (Template Id)
Request Body schema: application/json
Email Content (string) or Email Content (null) (Email Content)
Email Subject (string) or Email Subject (null) (Email Subject)
Name (string) or Name (null) (Name)
NotificationType (string) or null

Responses

Request samples

Content type
application/json
{
  • "email_content": "string",
  • "email_subject": "string",
  • "name": "string",
  • "type": "initial"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "email_content": "string",
  • "email_subject": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "type": "initial"
}

Receive email event

Authorizations:
OAuth2
Request Body schema: application/json
Array
Account Id (string) or Account Id (null) (Account Id)
Cluster (string) or Cluster (null) (Cluster)
email
required
string (Email)
event
required
string (LegalHold_SendGridDeliveryStatus)
Enum: "delivered" "bounce" "deferred" "dropped"
Matter Id (string) or Matter Id (null) (Matter Id)
Reason (string) or Reason (null) (Reason)
Response (string) or Response (null) (Response)
sg_event_id
required
string (Sg Event Id)
sg_message_id
required
string (Sg Message Id)
Task Id (string) or Task Id (null) (Task Id)
timestamp
required
integer (Timestamp)
Type (string) or Type (null) (Type)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
null

Delete SMTP config

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
null

Get SMTP config

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "host": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "port": 0,
  • "security": "None",
  • "username": "string"
}

Modify SMTP config

Authorizations:
OAuth2
Request Body schema: application/json
host
required
string (Host)
name
required
string (Name)
password
required
string (Password)
Port (integer) or Port (null) (Port)
security
required
string (LegalHold_SecurityTypes)
Enum: "None" "STARTTLS" "SSL/TLS"
username
required
string (Username)

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "name": "string",
  • "password": "string",
  • "port": 0,
  • "security": "None",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "host": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "port": 0,
  • "security": "None",
  • "username": "string"
}

Add SMTP config

Authorizations:
OAuth2
Request Body schema: application/json
host
required
string (Host)
name
required
string (Name)
password
required
string (Password)
Port (integer) or Port (null) (Port)
security
required
string (LegalHold_SecurityTypes)
Enum: "None" "STARTTLS" "SSL/TLS"
username
required
string (Username)

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "name": "string",
  • "password": "string",
  • "port": 0,
  • "security": "None",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "creation_date": "2019-08-24T14:15:22Z",
  • "deleted": false,
  • "host": "string",
  • "id": "string",
  • "modification_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "port": 0,
  • "security": "None",
  • "username": "string"
}

Test SMTP config without saving

Authorizations:
OAuth2
Request Body schema: application/json
host
required
string (Host)
name
required
string (Name)
password
required
string (Password)
Port (integer) or Port (null) (Port)
security
required
string (LegalHold_SecurityTypes)
Enum: "None" "STARTTLS" "SSL/TLS"
username
required
string (Username)

Responses

Request samples

Content type
application/json
{
  • "host": "string",
  • "name": "string",
  • "password": "string",
  • "port": 0,
  • "security": "None",
  • "username": "string"
}

Response samples

Content type
application/json
null

CustomFields

List Custom Fields

List custom fields.

Authorizations:
OAuth2
query Parameters
Cursor (string) or Cursor (null) (Cursor)
Examples: cursor=2022-02-22T11:11:11.12345
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/customFields' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create Custom Field

Create a custom field.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
description
required
string (Description)

Description

name
required
string (Name)

Name

required
required
boolean (Required)

Required

type
required
string (Type)

Type

Responses

Request samples

Content type
application/json
{
  • "description": "My custom field description",
  • "name": "My custom field",
  • "required": false,
  • "type": "keyword"
}

Response samples

Content type
application/json
{
  • "onna_id": "cf-my-custom-field-b20696ae9"
}

Download

Download Resource Content

Download the content of a resource, either binary file or html rendered content.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (The ID of the resource to download)
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET 'https://api.onna.com/v1/download/fd9f0c5339de42f9964e6afe9bf20259' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Jobs

Get Job Status

Track the progress of an AMQP job (e.g., team drives sync). Returns job status and details.

Authorizations:
OAuth2
path Parameters
job_id
required
string (Job Id)
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Request samples 

curl --request GET \
--url 'https://api.onna.com/v1/jobs/task:onna-onna-c18c434d-1752-4697-9e80-0f799e6181f4' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>'

Response samples

Content type
application/json
{ }

Preservations

Create Preservation

Create a preservation workspace with legal hold configuration.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Billing Number (string) or Billing Number (null) (Billing Number)

Billing number for customer billing tracking, max 40 characters.

Created By (string) or Created By (null) (Created By)

Creator identifier for the preservation workspace. Defaults to 'public-api' if not specified.

Description (string) or Description (null) (Description)

Short description explaining the purpose of this preservation.

Embeddings Enabled (boolean) or Embeddings Enabled (null) (Embeddings Enabled)
Default: false

Whether to enable embeddings for this preservation workspace.

Id (string) or Id (null) (Id)

Optional custom ID for the preservation workspace. If not provided, one will be auto-generated.

required
object (LegalHold)

Legal hold configuration. Include query (JSON Logic format) defining what data to preserve and other metadata as needed.

name
required
string (Name)

Display name of the preservation workspace. This will be the title shown in the UI.

Array of Tags (strings) or Tags (null) (Tags)

Labels for organizing and classifying the preservation workspace.

Responses

Request samples

Content type
application/json
{
  • "billing_number": "CASE-2024-001",
  • "description": "Data preservation for legal case 2024-001",
  • "embeddings_enabled": false,
  • "legal_hold": {
    },
  • "name": "Legal Hold Case 2024-001",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "created_by": "public-api",
  • "legal_hold": {
    },
  • "onna_id": "preservation-ws-c45fb2f5d72a41c2b085c2916511c633"
}

Get Preservable Datasource Types

Get types of datasources that can be preserved.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "types": [
    ]
}

Get Preservable Datasources

Get datasources that can be preserved.

Authorizations:
OAuth2
query Parameters
Cursor (string) or Cursor (null) (Cursor)

Pagination cursor

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "cursor": "next_cursor_value",
  • "items": [
    ],
  • "total": 5
}

Search Identities Discovery

Look up user identities within Onna for preservation.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
query
required
string (Query)

Search query for identities

Suggestions (boolean) or Suggestions (null) (Suggestions)
Default: true

Whether to include suggestions in the response

Responses

Request samples

Content type
application/json
{
  • "query": "jonathan@",
  • "suggestions": true
}

Response samples

Content type
application/json
{
  • "cursor": "next_cursor",
  • "items": [
    ],
  • "matching_source_accounts": 15
}

Delete Preservation

Delete a preservation workspace. The preservation must be completed (legal_hold.complete = true) before it can be deleted.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Update Preservation

Update a preservation workspace configuration. Modify legal_hold queries, billing_number, or other preservation settings. To mark a preservation as complete, use the dedicated finish endpoint.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Request Body schema: application/json
Billing Number (string) or Billing Number (null) (Billing Number)

Billing number for customer billing tracking, max 40 characters.

LegalHold (object) or null

Legal hold configuration. Set 'complete': true to finish the preservation. Include query (JSON Logic format) and other metadata as needed.

Responses

Request samples

Content type
application/json
{
  • "billing_number": "CASE-2024-001",
  • "legal_hold": {
    }
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get Preservation Details

Get preservation custodian information.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "identities": [
    ],
  • "preservation_query": {
    },
  • "total_identities": 1
}

Finish Preservation

Finish a preservation workspace by marking it as complete. This sets the legal_hold.complete flag to true, indicating that all required data has been preserved and the preservation process is finished. Once finished, the preservation workspace can be deleted if needed.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace to finish.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get Preserved Datasources

Get datasources that were preserved.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "datasources": [
    ]
}

Trigger Smart Action Check

Trigger smart action check to start preservation processing.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace.

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "estimated_completion": "2019-08-24T14:15:22Z",
  • "message": "string",
  • "progress": 0,
  • "started_at": "2019-08-24T14:15:22Z",
  • "status": "string"
}

Get Smart Action Status

Get preservation job status information.

Authorizations:
OAuth2
path Parameters
onna_id
required
string (Preservation ID)
Examples: preservation-ws-c45fb2f5d72a41c2b085c2916511c633

Unique ID of the preservation workspace.

query Parameters
View (boolean) or View (null) (View)
Default: true

Include detailed view

header Parameters
authorization
string (Authorization)

Authorization: Bearer ACCESS_TOKEN

The Authorization header must contain a Bearer Token, for more information see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "actions": 2650,
  • "complete": false,
  • "current": 2650,
  • "error": false,
  • "status": "running",
  • "target_version": 1,
  • "task_id": "task:onna-onna-0df0167f-1e59-4321-b2bc-ea6a6718676d",
  • "total": 10000,
  • "version": 1,
  • "when": "2025-12-04T14:50:05.973079+00:00"
}