Skip to main content

Hello world

After learning how to authenticate your requests and obtaining a valid token, it's time to get started, make your first calls to the API, and ingest real resources.

Sandbox Environment

When utilizing our API endpoints as outlined in the Developer Hub, it's essential to modify the URL structure for sandbox testing. All API endpoint URLs provided in the documentation are initially configured for the production environment using the base URL https://api.onna.com. However, you should replace this with https://sandbox.onna.com/api for the sandbox environment.

Create workspace​

Think of a workspace as the house to your project. You can add content and manage access to collaborate only with relevant people.

To create the workspace, make a POST request to the /workspaces endpoint.

curl --location --request POST '<https://api.onna.com/v1/workspaces>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0d3m0d3m0d3m0' \
--data-raw '{
  "name": "My workspace",
  "description": "My personal workspace",
  "tags": [
    "ideas",
    "projects"
  ]
}'

Where:

  • name is the name of your workspace
  • description is the title of the workspace in the UI
  • tags are tags to organize and classify your workspace

A successful response (201) returns the following payload:

{
  "onna_id": "d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0"
}

Where:

  • onna_id is the unique ID of your workspace

Now that the workspace is created, it's time to create a folder inside it to contain your data.

Create folder​

To create a folder, make a POST request to the /folders endpoint.

curl --location --request POST '<https://api.onna.com/v1/folders>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0d3m0d3m0d3m0' \
--data-raw '{
  "name": "My system data",
  "onna_parent_id": "d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0"
}'

Where:

  • name is the name of the folder
  • onna_parent_id is the ID of the workspace that must contain the folder

A successful response (201) returns the following payload:

{
    "onna_id": "0ec85634bf2c4d8db453a65551c36b8d"
}

Where:

  • onna_id is the unique ID of your folder

Now that the folder is created, you're ready to upload data to it.

Upload raw file​

You can upload raw files to your folder.

To upload a file, use the /files endpoint.

We use TUS

Our upload engine is based on the TUS protocol and treats every upload as a resumable file upload. Whatever the programming language you're using, it's possible that there's a library that integrates this protocol. For more information, see the TUS documentation.

Create empty raw file​

The first step to upload a file involves creating an empty file resource to which you're going to upload raw data. To do so, make a POST request to the /files endpoint, located under /resources.

curl --location --request POST 'https://api.onna.com/v1/resources/files' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer d3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0deMOd3m0d3m0d3m0d3m0' \
--data-raw '{
  "onna_parent_id": "0ec85634bf2c4d8db453a65551c36b8d",
  "ref": "Creativecommons-what-is-creative-commons_eng.pdf",
  "url": "https://wiki.creativecommons.org/images/3/35/Creativecommons-what-is-creative-commons_eng.pdf",
  "mime_type": "application/pdf",
  "name": "Creativecommons-what-is-creative-commons_eng.pdf",
  "path": "/images/3/35/Creativecommons-what-is-creative-commons_eng.pdf",
  "share_url": "https://wiki.creativecommons.org/images/3/35/Creativecommons-what-is-creative-commons_eng.pdf"
}'

Where:

  • onna_parent_id is the unique ID of the parent folder or workspace
  • ref is the reference or ID of the file at the source location
  • url is the URL of the file at the source location
  • mime_type is the media type of the file according to the MIME standard
  • name the name you want to give to your file once uploaded
  • path the path of the file at the source location
  • share_url URL to share the file at the source location
Optional parameters available

This request has optional parameters that you can use to refine your upload further. For more information, see our API reference.

A successful response (201) returns the following payload:

{
    "onna_id": "d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0",
    "onna_url": "d3m0d3m0d3m0d3m0d3m0d3m0d3m0d3m0"
}

Where:

  • onna_id is the unique ID of the resource in the platform
  • onna_url is the URI of the resource. It matches the resource's ID

Initialize TUS​

After creating the empty raw file, you must initialize the TUS protocol on the newly-created resource.

To initialize TUS, make a POST request to the /tus endpoint located under the resource's ID.

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

Where:

A successful request results in a 201 response.

Upload data to file​

It's now time to upload the file's content. Make a PATCH request to the /tus endpoint located under the resource's ID.

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

Where:

  • upload-offset is the offset where the upload should continue. When the file fits into one request, the offset is 0. When multiple requests are necessary, make the following ones using the PATCH method. For more information, see TUS documentation
  • data-raw is the raw content of your file

A successful upload returns a 204 response.

Processing​

Once you finish uploading it, the file is processed by our platform and becomes available for search en export from the UI.

Screenshot of the PDF preview in the UI

What's next​

Now that you learned how to upload raw files, you can try to explore how to ingest other resources from your applications. For example, you can ingest Ticket resources.

Last updated on