API Reference

Create a new research request. Credits are charged immediately. If clarifying questions are generated, the research waits for answers before starting.

Example Request

curl -X POST https://airesearchos.com/api/v1/research \
  -H "Authorization: Bearer aro_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Impact of GLP-1 drugs on the food industry",
    "mode": "dueDiligence",
    "reportLength": "standard",
    "skipClarifyingQuestions": true
  }'

Request Body

Response (with clarifying questions)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "clarifying",
  "creditsCharged": 25,
  "creditsRemaining": 125,
  "clarifyingQuestions": [
    "Which GLP-1 drugs should anchor the analysis?",
    "Should we focus on CPG companies, restaurant chains, or grocery retailers?",
    "Should the report emphasize analyst projections or consumer behavior data?"
  ],
  "createdAt": "2026-02-10T05:00:00Z"
}

Response (with skipClarifyingQuestions: true)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "creditsCharged": 25,
  "creditsRemaining": 125,
  "createdAt": "2026-02-10T05:00:00Z"
}

Submit answers to clarifying questions. Only valid when research status is "clarifying". Triggers the research to start.

Example Request

curl -X POST https://airesearchos.com/api/v1/research/550e8400-.../clarify \
  -H "Authorization: Bearer aro_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      "Focus on the full GLP-1 class including oral formulations",
      "CPG companies and restaurant chains",
      "Both Wall Street projections and consumer behavior data"
    ]
  }'

Request Body

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Research started"
}

Errors

409 - Research is not in "clarifying" status

Get the current status and progress of a research request. Use this for polling. The X-Poll-Interval header suggests a 10-second polling interval.

Example Request

curl https://airesearchos.com/api/v1/research/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer aro_sk_..."

Response (in progress)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "searching",
  "progress": 45,
  "currentStep": "Searching source 12 of 25...",
  "query": "Impact of GLP-1 drugs on the food industry",
  "mode": "dueDiligence",
  "creditsCharged": 25,
  "createdAt": "2026-02-10T05:00:00Z",
  "startedAt": "2026-02-10T05:00:05Z",
  "completedAt": null
}

Response (completed)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 100,
  "report": {
    "markdown": "# Impact of GLP-1 Drugs on the Food Industry\n\n...",
    "totalSources": 87,
    "totalLearnings": 42
  }
}

Status Values

Get the full structured report. Only available when status is "completed". Returns 409 otherwise.

Example Request

curl https://airesearchos.com/api/v1/research/550e8400-e29b-41d4-a716-446655440000/output \
  -H "Authorization: Bearer aro_sk_..."

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "query": "Impact of GLP-1 drugs on the food industry",
  "report": {
    "markdown": "# Full Report Title\n\n## Executive Summary\n...",
    "sections": [
      { "title": "Executive Summary", "content": "..." }
    ]
  },
  "sources": ["https://www.nature.com/articles/..."],
  "metadata": {
    "mode": "dueDiligence",
    "totalSources": 87,
    "totalLearnings": 42,
    "processingTimeSeconds": 505
  }
}

List your research requests with optional filtering and pagination.

Example Request

curl "https://airesearchos.com/api/v1/research?status=completed&limit=10" \
  -H "Authorization: Bearer aro_sk_..."

Query Parameters

Response

{
  "data": [
    {
      "id": "550e8400-...",
      "query": "Impact of GLP-1 drugs...",
      "mode": "dueDiligence",
      "status": "completed",
      "creditsCharged": 25
    }
  ],
  "pagination": { "total": 47, "limit": 20, "offset": 0, "hasMore": true }
}

Check your current credits balance. Daily credits reset automatically.

Example Request

curl https://airesearchos.com/api/v1/credits \
  -H "Authorization: Bearer aro_sk_..."

Response

{
  "daily": { "allocated": 150, "used": 25, "remaining": 125, "resetsAt": "2026-02-11T05:00:00Z" },
  "purchased": { "balance": 500 },
  "totalAvailable": 625
}