Skip to main content

​
Welcome to the Orion API

The Orion Public API enables you to programmatically create and run analysis jobs, retrieve insights, and configure webhooks for automated notifications. Use this API to integrate Orion’s data analysis capabilities into your existing workflows and applications.

Authentication

Authenticate with username/password to obtain access tokens for API requests.

Jobs

Create, run, and monitor analysis jobs using templates or direct configuration.

Webhooks

Configure webhooks to receive notifications when jobs complete.

Results

Retrieve analysis results and insights in markdown format.

​
Base URL

All API requests use the following base URL: 
/v1alpha

​
Authentication

The Orion API uses OAuth2 password flow for authentication. First obtain an access token by calling the login endpoint, then include it in subsequent requests.
1

Get an access token

Call POST /auth/login with your username and password to receive an access token.
2

Include token in requests

Add the token to the Authorization header of your API requests: bash Authorization: Bearer YOUR_ACCESS_TOKEN

​
Available Scopes

The API supports the following permission scopes:
ScopeDescription
adminFull administrative access
analystCreate and manage analysis jobs
data_heroExtended data access permissions
viewerRead-only access to results

​
Quick Start

Here’s a typical workflow for running an analysis job: 
# 1. Authenticate
TOKEN=$(curl -X POST '/v1alpha/auth/login' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'username=YOUR_USERNAME&password=YOUR_PASSWORD' \
  | jq -r '.access_token')

# 2. Get available templates

curl -X GET '/v1alpha/jobs/templates' \
 -H "Authorization: Bearer $TOKEN"

# 3. Create a job from a template

ASSIGNMENT_ID=$(curl -X POST '/v1alpha/jobs/' \
 -H "Authorization: Bearer $TOKEN" \
 -H 'Content-Type: application/json' \
 -d '{
"payload": {
"type": "template",
"template_id": "YOUR_TEMPLATE_ID",
"template_vars": {}
}
}' | jq -r '.')

# 4. Run the job

curl -X POST '/v1alpha/jobs/run' \
 -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{
    \"payload\": {
      \"type\": \"assignment\",
      \"assignment_id\": \"$ASSIGNMENT_ID\"
}
}"

# 5. Check job status

curl -X GET "/v1alpha/jobs/status?assignment_id=$ASSIGNMENT_ID" \
 -H "Authorization: Bearer $TOKEN"

​
Error Handling

The API uses standard HTTP status codes and returns validation errors in a consistent format:
Status CodeDescription
200Success
201Resource created
204Success, no content
422Validation error - check request body
{
  "detail": [
    {
      "loc": ["body", "payload", "template_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}