Research API Reference

Reference Starfire AI research jobs, asynchronous status, source collection, report results, citation metadata, limits, and project ownership.

Research API reference

The Research API is designed for multi-source work that can take longer than one synchronous generation request.

Resource model

The Alpha v1 architecture includes a research resource/run model for creating a research job, reading state, and retrieving results or source metadata when enabled.

Confirm exact paths and schemas in the current Developer Portal/OpenAPI.

Create a research job

A request can include concepts such as:

• research question
• depth
• source/query limits
• project or organization context
• output/report preferences

The create response should identify the durable research job rather than blocking until every search and verification step is complete.

Lifecycle

A research job can include stages such as:

planning
→ search/query execution
→ source retrieval
→ claim extraction/comparison
→ citation verification
→ report generation

Sources

Where the API exposes sources, preserve source URL/title/date/metadata needed by your application to display provenance.

A source being retrieved does not itself prove that every generated claim is supported by that source.

Results

The final result can be a report or structured research output depending on the active contract.

Limits

Research can be constrained by source count, query count, runtime, model/tool availability, credits, and organization policy.

Webhooks

Use completion/failure webhooks for backend automation rather than polling indefinitely when the event catalog supports research events.

Applications making important decisions should inspect source quality and citation support rather than treating a COMPLETED research run as proof that every claim is true.