---
title: "API reference"
description: "Getting started with the Ouro API."
date: "2025-07-14"
last_updated: "2026-05-23"
---

You can interact with the Ouro API through HTTP requests from any language or via our official Python and JavaScript bindings.

To install the official Python SDK, run the following command in your project directory:

```bash
pip install ouro-py
```

To install the official JavaScript SDK, run the following command in your project directory:

```bash
npm install ouro-js
```

You will need an Ouro account to take full advantage of the API.
Once you've made an account, create and copy your API key from your [settings](/settings/api-keys).
See the [Authentication section](/docs/developers#authentication) for more details.

<div className="grid grid-cols-2 gap-4 py-4">

<IconLink
  icon="service"
  href="/docs/developers/api/python"
  title="Python"
  description="Learn how to use the Ouro API in Python"
/>

<IconLink
  icon="service"
  href="/docs/developers/libraries"
  title="JavaScript"
  description="Install ouro-js - full SDK reference coming soon"
/>

</div>

<Callout type="info">
  A dedicated JavaScript SDK reference page is not published yet. Use the
  [Libraries](/docs/developers/libraries) page for install notes, or the [Python
  SDK](/docs/developers/api/python) for the most complete programmatic guide
  today.
</Callout>

<div className="hidden">

**`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**:

```json showLineNumbers
{
  "pat": "YOUR_API_KEY"
}
```

**Response**:

```json showLineNumbers
{
  "token": "GENERATED_TOKEN",
  "error": null
}
```

**Including the token in HTTP requests**<br/>Include your generated token in the Authentication header.

Example of how to include the token in a request:

```http
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**:

```json showLineNumbers
{
  "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**:

```json showLineNumbers
{
  "assetType": "string",
  "assetId": "uuid"
}
```

**Response**:

```json showLineNumbers
{
  "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.

---

### Share an asset

`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**:

```json showLineNumbers
{
  "permission": {
    "user": {
      "user_id": "uuid"
    },
    "role": "string"
  }
}
```

</div>