Integrate Aurora into a pipeline¶

Submit samples, follow jobs and retrieve results through HTTP or agent tools.

Use the client¶

The Python client handles uploads, polling and downloads. Start with one prediction, then use the API reference when your integration needs direct HTTP access.

Agent tools¶

An agent calls the same client through MCP tools. Install the mcp extra, start the server over standard input and output, and point a client at it:

{
  "mcpServers": {
    "auroraomics": {
      "command": "auroraomics",
      "args": [
        "mcp"
      ]
    }
  }
}

The server announces itself with these instructions:

Predict spatial gene expression from H&E images. Submit a prediction with submit, follow it with get_job until it ends, and write the result to a file with download_result.

Each tool is a plain function over the client, so an agent can do what a person can with the same key.

Tool	What it does
`list_models`	List the models this deployment serves, with what each one accepts.
`submit`	Submit a prediction and return the job it created, without waiting.
`get_job`	Read one job: its state, queue position, ETA and events.
`download_result`	Write a finished job's result to `path` and report where it went.
`resolve_genes`	Resolve symbols and aliases to the Ensembl ids every result is keyed by.

How a job runs and ends¶

A job leaves the in-flight states once and does not return.

State	Kind
`queued`	in flight
`validating`	in flight
`running`	in flight
`succeeded`	terminal
`failed`	terminal
`canceled`	terminal
`expired`	terminal

A job that ends in failed carries the error code that says why.

Re-send an identical request with the same Idempotency-Key, under the same API key, for as long as the job exists, and you get the same job back. No second job is created.

A retry after a timeout is safe.

A result expires after a bounded time, so treat the file you downloaded as the copy of record. Privacy and retention says how long it is kept.

Conventions every caller needs¶

GET https://api.auroraomics.org/v1/ needs no key and returns access_request, api_version, docs, lanes, llms_txt, models, openapi, qc, retention, service. lanes is empty while no runtime is accepting work.

Header	When	What to do with it
`X-Request-Id`	on every response	quote it when reporting a problem
`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`	on every response	the bucket's limit, what remains, and when it resets
`Retry-After`	on `429` and `503`	the number of seconds to wait; it is an instruction, not a hint
`Idempotency-Key`	on every `POST` you send	a retried request returns the same result instead of acting twice
`application/problem+json`	on every refusal	a body with a stable `code`, the `param` at fault and a `hint` written for a reader who cannot ask

What	Where
This site	https://docs.auroraomics.org
API	https://api.auroraomics.org/v1/
Website	https://auroraomics.org
Whole site in one fetch	https://docs.auroraomics.org/llms.txt, https://docs.auroraomics.org/llms-full.txt