Intro to Outset's API

Just launched- more information coming soon! (Summer 2025)

Welcome to the Outset API! This guide will help new users get up and running quickly. You'll learn how to authenticate, explore key endpoints, and perform basic operations using cURL and Python.

Prerequisites
Authentication
API Endpoints Overview
- List Studies
- Retrieve a Study
- Update a Study
Request Examples
Handling Responses
Next Steps

Prerequisites

You need an API key from your Outset account settings. You can obtain one here.
Basic familiarity with HTTP requests and JSON.

Authentication

All requests require an API key sent via the Authorization header with the Api-Key prefix:

Authorization: Api-Key YOUR_OUTSET_API_KEY

The OpenAPI version for this API is 3.0.3, and the current version is 0.1.0.

API Endpoints Overview

The base URL for production is:

https://api.outset.ai/v1

List Studies

Retrieve a paginated list of studies.

Endpoint: GET /studies/

Query parameters:

page (integer): Page number (optional).
page_size (integer): Results per page (optional).

Retrieve a Study

Get details for a specific study.

Endpoint: GET /studies/{id}/

Path parameter:

id (string, UUID, required): The study's unique identifier.

Update a Study

Modify a study's settings (only active and completion_url).

Endpoint: PATCH /studies/{id}/

Path parameter: id (string, UUID, required).

Body parameters (JSON):

active (boolean)
completion_url (string, URI)

Request Examples

cURL Example: List Studies

curl -X GET "https://api.outset.ai/v1/studies/?page=1&page_size=10" \
  -H "Authorization: Api-Key YOUR_OUTSET_API_KEY"

Python Example: Retrieve a Study

import requests
 
API_KEY = "YOUR_OUTSET_API_KEY"
BASE_URL = "https://api.outset.ai/v1"
 
study_id = "REPLACE_WITH_STUDY_ID"
response = requests.get(
    f"{BASE_URL}/studies/{study_id}/",
    headers={"Authorization": f"Api-Key {API_KEY}"}
)
response.raise_for_status()
data = response.json()
print(data)

Python Example: Update a Study

import requests
 
API_KEY = "YOUR_OUTSET_API_KEY"
BASE_URL = "https://api.outset.ai/v1"
 
study_id = "REPLACE_WITH_STUDY_ID"
payload = {
    "active": True,
    "completion_url": "https://yourapp.com/complete"
}
response = requests.patch(
    f"{BASE_URL}/studies/{study_id}/",
    headers={"Authorization": f"Api-Key {API_KEY}"},
    json=payload
)
response.raise_for_status()
print("Updated successfully:", response.json())

Handling Responses

Success

All successful responses return 200 OK with a JSON body containing the requested data.

Errors

When an error occurs, the Outset API (via Django REST Framework) returns a JSON payload with a top-level status of "error", and an errors array containing one or more error objects:

HTTP/1.1 400 Bad Request
Content-Type:application/json
 
{
  "status":"error",
  "errors":[
    {
      "field":null,
      "detail":"Authentication credentials were not provided.",
      "code":"not_authenticated"
    }
  ]
}

status will always be "error".
errors is an array of objects with:
- field: the name of the field causing the error, or null for general errors.
- detail: a human-readable description of the error.
- code: a machine-readable error code.

Status Codes

400 Bad Request: Validation errors.
401 Unauthorized: Missing or invalid authentication (detail).
403 Forbidden: Permission denied (detail).
404 Not Found: Resource not found (detail).

Next Steps

Explore additional endpoints under the schema tag to download the full OpenAPI schema (https://api.outset.ai/v1/schema/).
Integrate the API into your application, handling pagination and errors.

Happy coding!

Table of Contents