API Reference

Complete reference for the Helix Deep Research API.

Base URL

https://api.feeds.onhelix.ai

Authentication

All requests require API key authentication using the Bearer token scheme:

Authorization: Bearer YOUR_API_KEY

See the Authentication Guide for details on obtaining and using API keys.

Create Research Task

Submit a research topic to start a multi-agent research process.

POST /research/tasks

Request

Headers:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:

{
  "input": "What are the latest advancements in solid-state battery technology?",
  "title": "Solid-State Battery Research",
  "detail": "basic"
}

Parameters:

Parameter	Type	Required	Description
`input`	string	Yes	The research topic (minimum 1 character, trimmed)
`title`	string	No	Optional title for the research task
`detail`	string	No	Detail level for streaming: `basic` (default) or `detailed`
`output_schema`	any	Reserved	Not yet supported. Providing this will return a 400 error

Response

Status: 201 Created

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running",
    "input": "What are the latest advancements in solid-state battery technology?",
    "detail": "basic",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": null,
    "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
  }
}

Response Fields:

Field	Type	Description
`id`	string (UUID)	Unique research task identifier
`status`	string	Initial status: `running`
`input`	string	The research topic submitted
`detail`	string	Detail level (`basic` or `detailed`)
`createdAt`	string (ISO 8601)	Creation timestamp
`completedAt`	string\|null	Always `null` on creation
`streamUrl`	string	Relative URL for the SSE stream endpoint

Errors

400 Bad Request:

{
  "success": false,
  "error": "Research input is required"
}

{
  "success": false,
  "error": "output_schema is not yet supported. This feature is coming in a future release."
}

401 Unauthorized:

{
  "success": false,
  "error": "Invalid or missing API key"
}

Example

curl:

curl -X POST https://api.feeds.onhelix.ai/research/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Impact of generative AI on software development productivity",
    "detail": "basic"
  }'

JavaScript:

const response = await fetch('https://api.feeds.onhelix.ai/research/tasks', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    input: 'Impact of generative AI on software development productivity',
    detail: 'basic',
  }),
});

const { data } = await response.json();
console.log(`Task ID: ${data.id}`);
console.log(`Stream URL: ${data.streamUrl}`);

Python:

import requests

response = requests.post(
    'https://api.feeds.onhelix.ai/research/tasks',
    json={
        'input': 'Impact of generative AI on software development productivity',
        'detail': 'basic',
    },
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

data = response.json()['data']
print(f"Task ID: {data['id']}")
print(f"Stream URL: {data['streamUrl']}")

List Research Tasks

Retrieve all research tasks with pagination and optional status filtering.

GET /research/tasks

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Query Parameters:

Parameter	Type	Required	Description
`page`	number	No	Page number (min: 1, default: 1)
`pageSize`	number	No	Items per page (min: 1, max: 100, default: 20)
`status`	string	No	Filter by status: `RUNNING`, `COMPLETED`, `FAILED`, `STOPPED`

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "status": "completed",
        "input": "Impact of generative AI on software development...",
        "detail": "basic",
        "title": null,
        "result": {
          "report": "# Generative AI and Software Development...",
          "topics_researched": ["code-generation", "testing", "documentation"],
          "sources": [],
          "sub_reports_count": 3,
          "confidence_level": "high"
        },
        "usage": {
          "sub_researchers": 3,
          "sources_analyzed": 15
        },
        "createdAt": "2025-01-15T10:30:00.000Z",
        "completedAt": "2025-01-15T10:35:42.000Z",
        "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
      }
    ],
    "total": 45,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

Pagination Fields:

Field	Type	Description
`total`	number	Total number of research tasks
`page`	number	Current page number
`pageSize`	number	Items per page
`totalPages`	number	Total number of pages

Example

# List all research tasks
curl "https://api.feeds.onhelix.ai/research/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Filter by status
curl "https://api.feeds.onhelix.ai/research/tasks?status=COMPLETED&pageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Paginate
curl "https://api.feeds.onhelix.ai/research/tasks?page=2&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Research Task

Retrieve details for a specific research task.

GET /research/tasks/{taskId}

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`taskId`	string (UUID)	Yes	Unique research task identifier

Response

Status: 200 OK

Running task:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "running",
    "input": "Impact of generative AI on software development productivity",
    "detail": "basic",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": null,
    "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
  }
}

Completed task:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "input": "Impact of generative AI on software development productivity",
    "detail": "basic",
    "result": {
      "report": "# Generative AI and Software Development Productivity\n\n## Overview\n\n...",
      "topics_researched": [
        "code-generation-tools",
        "testing-automation",
        "documentation-generation"
      ],
      "sources": [
        {
          "url": "https://example.com/ai-productivity-study",
          "title": "AI Productivity in Software Engineering"
        }
      ],
      "sub_reports_count": 3,
      "confidence_level": "high"
    },
    "usage": {
      "sub_researchers": 3,
      "sources_analyzed": 15
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": "2025-01-15T10:35:42.000Z",
    "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
  }
}

Failed task:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "input": "Impact of generative AI on software development productivity",
    "detail": "basic",
    "error": "Workflow execution timed out",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "completedAt": "2025-01-15T10:45:00.000Z",
    "streamUrl": "/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream"
  }
}

Response Fields:

Field	Type	Description
`id`	string (UUID)	Unique research task identifier
`status`	string	`running`, `completed`, `failed`, or `stopped`
`input`	string	The research topic submitted
`detail`	string	Detail level (`basic` or `detailed`)
`title`	string\|null	Optional task title
`result`	object\|null	Research result (only when `completed`)
`usage`	object\|null	Usage statistics (only when `completed`)
`error`	string\|null	Error message (only when `failed`)
`createdAt`	string (ISO 8601)	Creation timestamp
`completedAt`	string\|null (ISO 8601)	Completion timestamp
`streamUrl`	string	Relative URL for the SSE stream

Result Fields (when completed):

Field	Type	Description
`report`	string	Comprehensive research report in Markdown
`topics_researched`	string[]	List of sub-topics investigated
`sources`	object[]	Web sources cited in the report
`sub_reports_count`	number	Number of sub-reports synthesized
`confidence_level`	string	`high`, `medium`, or `low`

Usage Fields (when completed):

Field	Type	Description
`sub_researchers`	number	Number of sub-researcher agents used
`sources_analyzed`	number	Total web sources analyzed

Errors

404 Not Found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Research task with id '550e8400-e29b-41d4-a716-446655440000' not found"
  }
}

Example

curl "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Research Snapshot

Returns the accumulated state of a research task and a sequence number for resuming the SSE stream. This avoids replaying all events from the beginning when reconnecting to a long-running task.

GET /research/tasks/{taskId}/snapshot

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`taskId`	string (UUID)	Yes	Unique research task identifier

Response

Status: 200 OK

{
  "success": true,
  "data": {
    "streamSequence": 42,
    "status": "active",
    "progress": {
      "topics_total": 3,
      "topics_completed": 1,
      "sources_found": 8
    },
    "topics": [
      {
        "topic": "solid-state-battery-materials",
        "index": 1,
        "status": "completed"
      },
      { "topic": "ev-integration", "index": 2, "status": "started" },
      { "topic": "manufacturing-challenges", "index": 3, "status": "started" }
    ],
    "sources": [
      {
        "url": "https://example.com/research",
        "title": "Battery Research Paper",
        "topic": "solid-state-battery-materials"
      }
    ],
    "result": null,
    "error": null,
    "timestamp": 1705312242000
  }
}

Response Fields:

Field	Type	Description
`streamSequence`	number	Sequence number to pass as `fromSequence` when connecting to the SSE stream
`status`	string	`active`, `completed`, or `failed`
`progress.topics_total`	number	Total sub-topics being researched
`progress.topics_completed`	number	Sub-topics completed so far
`progress.sources_found`	number	Web sources discovered so far
`topics`	array	List of topics with their current status (`started` or `completed`)
`sources`	array	Accumulated web sources with url, title, and topic
`result`	object\|null	Research result (only when complete)
`error`	string\|null	Error message (only when failed)
`timestamp`	number	Server timestamp (milliseconds since epoch)

Errors

400 Bad Request:

{
  "success": false,
  "error": "No stream available for this task"
}

{
  "success": false,
  "error": "Streaming not available"
}

404 Not Found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Research task with id '550e8400-e29b-41d4-a716-446655440000' not found"
  }
}

Example

curl:

curl "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000/snapshot" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript:

const response = await fetch(
  `https://api.feeds.onhelix.ai/research/tasks/${taskId}/snapshot`,
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);

const { data: snapshot } = await response.json();
console.log(`Status: ${snapshot.status}`);
console.log(
  `Progress: ${snapshot.progress.topics_completed}/${snapshot.progress.topics_total}`
);
console.log(`Resume stream from sequence: ${snapshot.streamSequence}`);

Python:

import requests

response = requests.get(
    f'https://api.feeds.onhelix.ai/research/tasks/{task_id}/snapshot',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

snapshot = response.json()['data']
print(f"Status: {snapshot['status']}")
print(f"Progress: {snapshot['progress']['topics_completed']}/{snapshot['progress']['topics_total']}")
print(f"Resume stream from sequence: {snapshot['streamSequence']}")

Stream Research Task (SSE)

Stream real-time research progress via Server-Sent Events.

GET /research/tasks/{taskId}/stream

Request

Headers:

Authorization: Bearer YOUR_API_KEY

Path Parameters:

Parameter	Type	Required	Description
`taskId`	string (UUID)	Yes	Unique research task identifier

Query Parameters:

Parameter	Type	Required	Description
`detail`	string	No	Override detail level: `basic` or `detailed`. Defaults to the task's `detail` value
`fromSequence`	integer	No	Resume from this sequence number (default: 0). Use for reconnection

Response

Content-Type: text/event-stream

The stream emits events as the research progresses. Each event has a type and JSON data payload.

Event types (basic mode): topic, progress, source, result, error, done

Additional event types (detailed mode): agent, tool, text, thinking

See the Streaming Guide for complete event documentation.

Stream format:

event: topic
data: {"topic":"solid-state-battery-materials","index":1,"status":"started"}
id: 3

event: source
data: {"url":"https://example.com/research","title":"Battery Research Paper","topic":"solid-state-battery-materials"}
id: 7

event: progress
data: {"topics_total":3,"topics_completed":1,"sources_found":5}
id: 12

event: result
data: {"report":"# Research Report...","topics_researched":[...],"sources":[...],"sub_reports_count":3,"confidence_level":"high"}
id: 45

event: done
data: {}
id: 46

Reconnection: If your connection drops, reconnect with fromSequence set to the last id you received. The server sends keepalive comments (: lines) every 15 seconds to keep the connection alive.

Errors

400 Bad Request:

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "No stream available for this task"
  }
}

404 Not Found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Research task with id '550e8400-e29b-41d4-a716-446655440000' not found"
  }
}

Example

curl:

curl -N "https://api.feeds.onhelix.ai/research/tasks/550e8400-e29b-41d4-a716-446655440000/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript (EventSource):

const taskId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://api.feeds.onhelix.ai/research/tasks/${taskId}/stream`;

const eventSource = new EventSource(url, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
});

eventSource.addEventListener('topic', (e) => {
  const { topic, status } = JSON.parse(e.data);
  console.log(`Topic ${topic}: ${status}`);
});

eventSource.addEventListener('progress', (e) => {
  const { topics_completed, topics_total, sources_found } = JSON.parse(e.data);
  console.log(
    `${topics_completed}/${topics_total} topics, ${sources_found} sources`
  );
});

eventSource.addEventListener('result', (e) => {
  const result = JSON.parse(e.data);
  console.log('Report:', result.report);
});

eventSource.addEventListener('done', () => eventSource.close());

Python (sseclient):

import requests
import sseclient
import json

task_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://api.feeds.onhelix.ai/research/tasks/{task_id}/stream'

response = requests.get(
    url,
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    stream=True,
)

client = sseclient.SSEClient(response)

for event in client.events():
    data = json.loads(event.data)

    if event.event == 'progress':
        print(f"Progress: {data['topics_completed']}/{data['topics_total']}")
    elif event.event == 'result':
        print(f"Report:\n{data['report']}")
    elif event.event == 'done':
        break
    elif event.event == 'error':
        print(f"Error: {data['message']}")
        break

Error Responses

All endpoints may return these standard errors:

400 Bad Request

Invalid request parameters or body:

{
  "success": false,
  "error": "Research input is required"
}

401 Unauthorized

Missing or invalid API key:

{
  "success": false,
  "error": "Invalid or missing API key"
}

404 Not Found

Resource not found:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Research task with id '...' not found"
  }
}

500 Internal Server Error

Server error:

{
  "success": false,
  "error": "An internal error occurred. Please try again later."
}

Best Practices

Prefer Streaming Over Polling

Use the SSE stream endpoint to consume results in real-time rather than polling GET /research/tasks/{id}. Streaming provides immediate visibility into progress and avoids unnecessary API calls.

Handle Reconnection

SSE connections can drop. Use the fromSequence query parameter to resume from where you left off:

let lastSequence = 0;

function connect() {
  const url = `https://api.feeds.onhelix.ai/research/tasks/${taskId}/stream?fromSequence=${lastSequence}`;
  const es = new EventSource(url, {
    headers: { Authorization: 'Bearer YOUR_API_KEY' },
  });

  es.onmessage = (e) => {
    lastSequence = parseInt(e.lastEventId, 10);
  };

  es.onerror = () => {
    es.close();
    setTimeout(connect, 3000);
  };
}

Choose the Right Detail Level

Use basic (default) for production UIs — fewer events, lower bandwidth
Use detailed for debugging, developer tools, or agent visualization

Next Steps

Quickstart Guide: Create your first research task in 5 minutes
Overview: Understand how the multi-agent system works
Streaming Guide: Full SSE event reference and code examples
Authentication: API key best practices

API Reference

Base URL​

Authentication​

Create Research Task​

Request​

Response​

Errors​

Example​

List Research Tasks​

Request​

Response​

Example​

Get Research Task​

Request​

Response​

Errors​

Example​

Get Research Snapshot​

Request​

Response​

Errors​

Example​

Stream Research Task (SSE)​

Request​

Response​

Errors​

Example​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

500 Internal Server Error​

Best Practices​

Prefer Streaming Over Polling​

Handle Reconnection​

Choose the Right Detail Level​

Next Steps​

Base URL

Authentication

Create Research Task

Request

Response

Errors

Example

List Research Tasks

Request

Response

Example

Get Research Task

Request

Response

Errors

Example

Get Research Snapshot

Request

Response

Errors

Example

Stream Research Task (SSE)

Request

Response

Errors

Example

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Best Practices

Prefer Streaming Over Polling

Handle Reconnection

Choose the Right Detail Level

Next Steps