# Agent integration guide

The Genomic Intelligence API runs six DNA sequence analysis tasks built on transformer language models. Each task is a single HTTP endpoint: `POST /v1/tasks/{task}/predict`. The same six tasks are also reachable over [MCP](mcp.md).

This page orients you to the REST API and points to the canonical guides and reference. For the step-by-step walkthrough, jump to the [REST API guide](rest-api.md).

Base URL: `https://api.genomicintelligence.ai`

## Overview

Every endpoint shares one contract:

- **Six tasks**, each at `POST /v1/tasks/{task}/predict`: `promoter`, `splice`, `enhancer`, `chromatin`, `expression`, `annotation`.
- **Bearer authentication** on every `/v1/*` route. Public routes (no key): `/health`, `/docs`, `/redoc`, `/v1/openapi.json`.
- **One success envelope**: `{data, meta}` on every 2xx and 202. `data` carries task-specific fields; `meta` is uniform across tasks.
- **One error envelope**: `{error: {code, message, request_id, details?}}`.
- **Synchronous by default, asynchronous on request.** Add `Prefer: respond-async` to submit a job: the call returns `202` with a `job_id`, and you poll `GET /v1/tasks/jobs/{job_id}` until it reaches a terminal state.

The live OpenAPI document at `https://api.genomicintelligence.ai/v1/openapi.json` is the machine-readable source of truth. It carries `oneOf` discriminators on `data.task` and on `error.details`, so generated typed clients (Python pydantic, TypeScript zod) narrow correctly. A rendered view is at `https://api.genomicintelligence.ai/redoc`.

## Authentication

All `/v1/*` routes require an API key:

```http
Authorization: Bearer gi_...
```

Verify connectivity before integrating:

```bash
curl -sS https://api.genomicintelligence.ai/health
# {"status":"healthy","version":"YYYY.MM.DD.iter (commit)"}

curl -sS -H "Authorization: Bearer $GI_API_KEY" \
     https://api.genomicintelligence.ai/v1/tasks/promoter/models
# 200 with {task, default_model, models: [...]}
```

Model-listing endpoints return a flat object, not the `{data, meta}` envelope used by predict endpoints. Per-key rate caps, the `RateLimit-*` headers, and the concurrency limiter are documented in [Limits](reference/limits.md).

## Get started

The [REST API guide](rest-api.md) has the full walkthrough: the contract, the downloadable integration kit (a drop-in single-file `gi_client.py` depending only on `requests`), simple sync and async examples in Python, and self-contained recipes — promoters across a gene list, async annotation polling, rate-limit-aware retry, typed error handling.

### Using with an AI coding agent

If you are integrating from inside an AI coding agent, point it at this page and the [llms.txt](https://docs.genomicintelligence.ai/llms.txt) index so it works from the same contract. To have an agent inherit these rules across sessions, save this guide into your repo as `AGENTS.md` (or `CLAUDE.md`) — the raw Markdown is served at [docs.genomicintelligence.ai/AGENTS.md](https://docs.genomicintelligence.ai/AGENTS.md). If your agent runs in an MCP client such as Claude Desktop, Cursor, or Claude Code, the [MCP server](mcp.md) reaches the same six tasks with typed tools.

## The six tasks

Each task accepts a DNA `sequence` (and a `sequence_name` label) and returns task-specific fields under `data`. See the [Tasks](tasks.md) page for biology, task-specific options, and output fields; per-task length caps are in [Limits](reference/limits.md).

| Task | Endpoint | Output |
|---|---|---|
| [`promoter`](tasks.md#promoter) | `POST /v1/tasks/promoter/predict` | Promoter-region probabilities (binary classification). |
| [`splice`](tasks.md#splice) | `POST /v1/tasks/splice/predict` | Per-token acceptor and donor splice-site predictions. |
| [`enhancer`](tasks.md#enhancer) | `POST /v1/tasks/enhancer/predict` | Developmental and housekeeping enhancer-activity scores (regression). |
| [`chromatin`](tasks.md#chromatin) | `POST /v1/tasks/chromatin/predict` | Multi-label chromatin features grouped into tracks. |
| [`annotation`](tasks.md#annotation) | `POST /v1/tasks/annotation/predict` | Gene-finding transcript intervals (TSS/PolyA detection). |
| [`expression`](tasks.md#expression) | `POST /v1/tasks/expression/predict` | Predicted gene expression in log(TPM+1), from sequence plus an experimental description. |

## Model selection

Each task has a default model and may offer alternatives. List them with `GET /v1/tasks/{task}/models`; the response is a flat object with `default_model` and a `models` array (see ReDoc for the schema). If you do not name a model the task uses `default_model`; to pick one, pass its `name` in `options.model`. Beyond the default human models, `promoter` offers species-specific variants (Drosophila, yeast, Arabidopsis) and DNABERT k-mer variants exist for `promoter`, `enhancer`, and `chromatin`. The model-list endpoint is authoritative for what each task currently serves.

## Error handling

Every error uses the envelope `{error: {code, message, request_id, details?}}`. Switch on `error.code`, not on `error.message` — the code is the authoritative discriminator; the message is for human-readable logs and can change without notice. Map every code to one of three actions:

1. **Retryable transient** (`429`, `503`): honor `Retry-After`; if absent, back off exponentially, capped at 30 s.
2. **Permanent client error** (other `4xx`): surface `error.message`; do not retry. `422` messages are deterministic and safe to echo.
3. **Server error** (`5xx` other than `503`): capture `request_id`, retry once at most, then escalate.

`504 gateway_timeout` is the one response with no envelope (it comes from the edge proxy) — treat it as a signal to switch to async. The full code catalog, typed `details` shapes, and handling notes are in [Errors](reference/errors.md).

## Next steps

- [REST API guide](rest-api.md): the REST walkthrough, the downloadable `gi_client.py`, and runnable recipes.
- [Errors](reference/errors.md): the `error.code` catalog and handling strategy.
- [Limits](reference/limits.md): per-task caps, rate quotas, and async job TTL.
- [Support](resources/support.md): contact, bug reports, and production access.
- [MCP server](mcp.md): the six tasks over Model Context Protocol.
- [API reference (ReDoc)](https://api.genomicintelligence.ai/redoc): the full rendered OpenAPI.
- [OpenAPI schema](https://api.genomicintelligence.ai/v1/openapi.json): the live machine-readable contract.