API

REST API Overview

The OpenAnalyst REST API provides full programmatic access to the platform. You can query datasets, retrieve reports, trigger AI agent runs, and manage resources — all without using the web interface. The API follows REST conventions and returns JSON responses.

The base URL for all API requests is:

https://api.openanalyst.com/v1

All endpoints require HTTPS. HTTP requests will be redirected to HTTPS automatically.

Authentication

Authenticate API requests by including your API key in the Authorization header using the Bearer scheme.

Authorization: Bearer oa_your_api_key_here

To generate an API key:

1. Log in to app.openanalyst.com.
2. Navigate to Settings in the sidebar.
3. Click the API Keys tab.
4. Click Generate New Key, give it a descriptive label, and set an optional expiry date.
5. Copy the key immediately — it will not be shown again.

Key Endpoints

The following table summarizes the most commonly used API endpoints:

Example Requests

The following examples show how to authenticate and make requests using curl and the JavaScript fetch API.

List datasets using curl

curl -X GET https://api.openanalyst.com/v1/datasets \
  -H "Authorization: Bearer oa_your_api_key_here" \
  -H "Content-Type: application/json"

Execute a query using curl

curl -X POST https://api.openanalyst.com/v1/queries \
  -H "Authorization: Bearer oa_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset_id": "ds_abc123",
    "query": "SELECT date, revenue FROM sales WHERE date >= \'2024-01-01\' ORDER BY date DESC LIMIT 100"
  }'

Run an AI agent using JavaScript fetch

const response = await fetch('https://api.openanalyst.com/v1/agents/run', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer oa_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'agent_xyz789',
    task: 'Summarize weekly sales performance and flag any anomalies.',
    context: {
      dataset_id: 'ds_abc123',
      date_range: { start: '2024-01-01', end: '2024-01-07' },
    },
  }),
});

const data = await response.json();
console.log(data.run_id); // Poll this ID for results

Pagination

List endpoints return paginated results. Use the page and per_page query parameters to control pagination:

GET /datasets?page=2&per_page=25

Each paginated response includes a meta object:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 25,
    "total": 143,
    "total_pages": 6
  }
}

Rate Limits

API rate limits are applied per workspace and vary by plan:

When a rate limit is exceeded, the API returns a 429 Too Many Requests response. The Retry-After header indicates how many seconds to wait before retrying.

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with a code and message field:

{
  "error": {
    "code": "DATASET_NOT_FOUND",
    "message": "No dataset with the given ID exists in this workspace.",
    "status": 404
  }
}

Common error codes:

Webhook Callbacks

For long-running operations such as agent runs and large query executions, you can provide a webhook URL to receive a callback when the operation completes, rather than polling.

curl -X POST https://api.openanalyst.com/v1/agents/run \
  -H "Authorization: Bearer oa_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xyz789",
    "task": "Generate monthly revenue summary.",
    "webhook_url": "https://your-app.com/webhooks/openanalyst"
  }'

OpenAnalyst will send a POST request to the provided URL with a JSON payload containing the run ID, status, and result when the operation finishes. Webhook payloads are signed with an X-OpenAnalyst-Signature header for verification.