Skip to main content
API docs by Redocly

Onna Platform API (v1.0.0)

Download OpenAPI specification:Download

Onna API Team: support@onna.com URL: https://dev.onna.com/help License: Apache 2.0 Terms of Service

Introduction

Onna

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)
client_secret
string (Client Secret)
grant_type
string (Grant Type)
Default: "client_credentials"

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": "string",
  • "expires_in": 0,
  • "token_type": "string"
}

Current User

Return information about the currently authenticated user.

Authorizations:
OAuth2
header Parameters
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "id": "string",
  • "name": "string",
  • "surname": "string"
}

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 (Cursor)
Example: cursor=2022-02-22 11:11:11.12345//d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0
header Parameters
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

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

Short description of the workspace.

name
required
string (Name)

Display name of the workspace.

tags
Array of strings (Tags) <= 10000 items

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",
  • "name": "My workspace",
  • "tags": [
    ]
}

Response samples

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

Delete Workspace

Delete a Workspace.

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

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)
Example: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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
{
  • "description": "My personal workspace",
  • "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)
Example: myworkspace-ZPM9Jf4zQ

Unique ID of the workspace.

header Parameters
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

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

Short description of the workspace.

name
string (Name)

Display name of the workspace.

tags
Array of strings (Tags) <= 10000 items

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",
  • "name": "My workspace",
  • "tags": [
    ]
}

Response samples

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

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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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": [
    ]
}

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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Request Body schema: application/json
comment
string (Comment)

Comment type of file.

creation_date
string <date-time> (Creation Date)

Date when file was created.

creator
string (Creator)

User that created the file.

deleter
string (Deleter)

User that deleted the file.

deletion_date
string <date-time> (Deletion Date)

Date when file was deleted.

description
string (Description)

File description.

mime_type
string (Mime Type)

MIME type of file.

name
string (Name)

File name.

onna_parent_id
required
string (Parent ID)

The ID of the parent Workspace or Folder.

path
string (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 (Share URL)

Link or invite to share file (at origin).

status
string (Status)

File status: Deleted, Archived, etc.

tags
Array of strings (Tags) <= 1000 items

List of tags associated to the file in the origin.

type
string (Type)

Type of file.

update_date
string <date-time> (Update Date)

Date when the file was last updated.

updater
string (Updater)

The last user to update the file.

url
required
string (URL)

A Unique Resource Locator for the file at the origin.

version
string (Version)

Version.

Responses

Request samples

Content type
application/json
{
  • "onna_parent_id": "da72de92fef04c6a9cc5cfe018fa9cd6"
}

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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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
{
  • "onna_parent_id": "da72de92fef04c6a9cc5cfe018fa9cd6"
}

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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

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

Assignee group.

assignees
Array of strings (Assignees) <= 1000 items

List of users assigned to the ticket.

author
string (Author)

The user that created the ticket.

category
string (Category)

Category.

Array of objects (Comments) <= 5000 items

List of messages associated to the ticket.

creation_date
string <date-time> (Creation Date)

Date when the ticket was created.

description
string (Description)

Description.

followers
Array of strings (Followers) <= 1000 items

List of users following the ticket.

name
required
string (Name)

Title.

onna_parent_id
required
string (Parent ID)

The ID of the parent Folder.

priority
string (Priority)

Priority: high, medium, low, etc.

reactions
Array of strings (Reactions) <= 1000 items

List of reactions.

ref
required
string (Reference)

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

requester
string (Requester)

The user that requested the ticket.

severity
string (Severity)

Severity: high, medium, low, etc.

status
string (Status)

Ticket status: open, closed, archived, etc.

subcategory
string (Subcategory)

Subcategory.

tags
Array of strings (Tags) <= 1000 items

List of tags associated to the ticket in the origin.

type
string (Type)

Type of ticket.

update_date
string <date-time> (Update Date)

Date when the ticket was last updated.

updater
string (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
{}

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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, 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
{}

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
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Responses

Request samples 

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

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
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Responses

Request samples 

curl 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'PATCH' \
  -H 'authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0d3m0d3m0d3m0' \
  -H 'content-type: application/offset+octet-stream' \
  -H 'tus-resumable: 1.0.0' \
  -H 'upload-offset: 0' \
  --data-raw $'%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
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Responses

Request samples 

curl 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'POST' \
  -H 'authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0d3m0d3m0d3m0' \
  -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)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Responses

Request samples 

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

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
onna_id
required
string (Onna Id)
header Parameters
authorization
string (Authorization)

The Authorization header contains your access token as a Bearer Token:

Authorization: Bearer ACCESS_TOKEN

You can obtain an access token through an OAuth flow such as the client credentials flow. For more information on obtaining an access token, see "Obtaining an access token".

Responses

Request samples 

curl -i 'https://api.onna.com/v1/upload/d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0/tus' \
  -X 'OPTIONS' \
  -H 'authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0d3m0d3m0d3m0' \
  -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"
}