> ## Documentation Index
> Fetch the complete documentation index at: https://aidocs.ethanbragdon.icu/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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.

<Warning>
  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.
</Warning>