API reference

Getting started with the Ouro API.

You can interact with the API through HTTP requests from any language, via our official Python bindings, our official Node.js library.

To install the official Python bindings, run the following command:

pip install ouro-py

To install the official Node.js library, run the following command in your Node.js project directory:

npm install ouro-js

You'll need an Ouro account before you can use the API. Once you're signed up, create and copy your API key from your account settings. See the Authentication section for more details.

Web API only

Generate an access token

POST https://api.ouro.foundation/users/get-token

Client libraries will handle this step automatically. Prior to any other HTTP requests, exchange your API key for a token. The token must be included in your Authentication header for all requests.

Request body:

{
  "pat": "YOUR_API_KEY"
}

Response:

{
  "token": "GENERATED_TOKEN",
  "error": null
}

Including the token in HTTP requests
Include your generated token in the Authentication header.

Example of how to include the token in a request:

GET https://api.ouro.foundation/users/hermes
Authorization: GENERATED_TOKEN

Users

Follow a user

PUT https://api.ouro.foundation/users/:username/follow

Follows the user specified by username. If you are already following the user, the request will unfollow the user.

URL parameters:

username (string). The username of the requested user.

No request body required

Read a user's follows

GET https://api.ouro.foundation/users/:username/follows

Retrieves a list of users being followed and following the specified user.

URL parameters:

username (string). The username of the requested user.

Response:

{
  "data": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "followed_user_id": "uuid",
      "added_at": "timestamp"
    }
    // Continued...
  ],
  "error": null
}

Common

Routes common to all of the elements and assets they contain.

Purchase an asset

POST https://api.ouro.foundation/elements/common/purchase-asset

Initiates the purchase of an asset. Define the asset you want to purchase by it's type and ID. The request will fail if your account does not have enough credit to cover the cost of the asset.

Request body:

{
  "assetType": "string",
  "assetId": "uuid"
}

Response:

{
  "data": {
    "charge": {
      // Charge details object
    },
    "transfer": {
      // Transfer details object
    }
  },
  "error": null
}

Read permissions

GET https://api.ouro.foundation/datasets/:id/permissions

Retrieves the permissions settings of a specific dataset.

URL parameters:

id (uuid). The ID of the requested dataset.

PUT /datasets/:id/share

Updates permission settings for a specific dataset by adding the specified user. Only users with admin permissions on the dataset have the ability to share a dataset.

Permission grants the user a read, write, or admin role on the asset as specified.

URL parameters:

id (uuid). The ID of the requested dataset.

Request body:

{
  "permission": {
    "user": {
      "user_id": "uuid"
    },
    "role": "string"
  }
}

Delete an asset

DELETE /datasets/:id

Deletes a specific dataset. Only users with admin permissions on the dataset have the ability to delete a dataset.

URL parameters:

id (uuid). The ID of the dataset to delete.

Datasets

The Earth layer is where data is stored and managed on Ouro. You can perform CRUD operations on any type of file or structured dataset (relational database table).

Although handled as a single asset type, there are two main stages of Dataset:

Base, referred to as File
Structured, often just referred to as a Dataset

Create a dataset from a file

POST https://api.ouro.foundation/datasets/create/from-file

Creates a new dataset from a file with a size limit of 5GB.

Tabular data like .csv files will automatically be transformed into structured datasets

Request body:

{
  "metadata": {
    "id": "uuid",
    "type": "string",
    "path": "string"
  },
  "preview": [],
  "visibility": "string",
  "monetization": "string",
  "price": "number",
  "name": "string",
  "description": "string"
}

The metadata object is the response returned after a file is added. Soon, the file upload to create dataset flow will be a single step instead of first having to upload the file, then create a dataset from it.

When possible, prefer to use one of the client libraries so that schema validation and other helpful utilities can help you.

Response:

{
  "data": {
    "id": "uuid",
    "name": "glob",
    "description": "The first asset ever added to Ouro!",
    "visibility": "public",
    "asset_stage": "base"
    // More fields...
  },
  "warning": {},
  "error": null
}

Create a dataset from a schema

POST https://api.ouro.foundation/datasets/create/from-schema

Creates a new dataset based on a predefined schema defined by a CREATE TABLE statement in SQL. This route is a good option for when you need a high level of control over the structure and behavior of the created structured dataset.

Use available PUT methods to load data into the dataset in a subsequent request.

Request body:

{
  "dataset": {
    "queryString": "string",
    "visibility": "string",
    "monetization": "string",
    "price": "number",
    "description": "string"
  }
}

For example, a queryString may look like the following. You don't need to worry about newlines or other spacing issues as long as you have valid SQL. Also, don't even try any SQL injection attacks - they won't work!

CREATE TABLE datasets.iris_dataset (
    id SERIAL PRIMARY KEY,
    sepal_length_cm DECIMAL(3, 1),
    sepal_width_cm DECIMAL(3, 1),
    petal_length_cm DECIMAL(3, 1),
    petal_width_cm DECIMAL(3, 1),
    species VARCHAR(20)
);

The name and description of the created dataset will be inferred from the SQL statement defined by the queryString string. In this example, the name of the created dataset will be iris_dataset.

Response:

{
  "data": {
    "id": "uuid",
    "name": "string",
    "description": "string",
    "visibility": "public",
    "asset_stage": "structured"
    // More fields...
  },
  "error": null
}

Create a dataset from a Service

POST https://api.ouro.foundation/datasets/create/from-service

Creates a new dataset by importing data from an external service connected in the Water layer. If the service requires authentication, be sure to configure that with the Service asset before using this route.

It currently only supports structured-dataset-type responses. For example, a Service should return an array of objects that can be loaded as rows of a dataset.

The schema of the created dataset will automatically be inferred from the response schema.

Request body:

{
  "route": {
    "id": "uuid"
  },
  "dataset": {
    "locations": "string",
    "name": "string",
    "description": "string",
    "visibility": "string",
    "monetization": "string",
    "price": "number"
  }
}

We don't currently support passing any parameters (URL, query, POST body, etc.) to Routes through this interface, but it's on the roadmap.

dataset.location field allows you to specify where on the Route response to expect the data array. Many APIs, Ouro's included, return API responses as objects with additional metadata and information beyond the requested resource. Set this value to a string with the location specified in dot notation.

For example, data.values will get the array of values located on the following multi-level object:

{
  "data": {
    "type": "array",
    "values": [
      { "id": 0, "value": 10 },
      { "id": 1, "value": 14 }
      // More values...
    ]
  },
  "error": null
}

Response:

{
  "data": {
    "id": "uuid",
    "name": "string",
    "description": "string",
    "visibility": "public",
    "asset_stage": "structured"
    // More fields...
  },
  "error": null
}

Read context datasets

GET https://api.ouro.foundation/datasets

Retrieves a list of all of the authenticated user's datasets, including assets that have been shared with them and assets they have purchased.

When a user has an organization context set, they will get assets that are specific to that context.

Read a dataset

GET https://api.ouro.foundation/datasets/:id

Retrieves details about a specific dataset.

URL parameters:

id (uuid). The ID of the requested dataset.

Read a dataset's data

GET https://api.ouro.foundation/datasets/:id/data

Retrieves the data contained within a specific dataset. Depending on the dataset stage, you will either get a URL pointing to the underlying data, or

Base datasets return a secure URL that you can use to access the file data
Structured datasets return the data as an array of objects

URL parameters:

id (uuid). The ID of the requested dataset.

Read a dataset's schema

GET https://api.ouro.foundation/datasets/:id/schema

Retrieves the schema of a specific dataset. Specifies the columns of the dataset and their datatype, as well as any foreign key and index information.

Currently only has relevant data for structured datasets.

URL parameters:

id (uuid). The ID of the requested dataset.

Read a dataset's stats

GET https://api.ouro.foundation/datasets/:id/stats

Provides statistical information about a specific dataset.

For structured datasets, information like row count is returned. For files, you get extended file metadata like file size and type.

URL parameters:

id (uuid). The ID of the requested dataset.

API reference

Generate an access token

Users

Follow a user

Read a user's follows

Common

Purchase an asset

Read permissions

Share an asset

Delete an asset

Datasets

Create a dataset from a file

Create a dataset from a schema

Create a dataset from a Service

Read context datasets

Read a dataset

Read a dataset's data

Read a dataset's schema

Read a dataset's stats