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

# API Reference

> REST API for the Remyx ExperimentOps platform

# API Reference

The Remyx REST API is available at `https://engine.remyx.ai/api/v1.0`. All endpoints require a Bearer token in the `Authorization` header.

```bash theme={null}
curl -H "Authorization: Bearer rmxu_xxxxxxxxxxxxxxxxxxxxxxxx" \
  https://engine.remyx.ai/api/v1.0/interests
```

<Info>
  Create a named API key at **Account > API Access** in the Remyx app, or at [studio.remyx.ai/account](https://studio.remyx.ai/account). Each route is gated by [scopes](/api-reference/scopes); see [Authentication](#authentication) below.
</Info>

***

## Experiments

Manage experiments, track outcomes, and log decisions.

### List Experiments

```
GET /api/v1.0/experiments
```

| Parameter            | Type    | Description                                            |
| -------------------- | ------- | ------------------------------------------------------ |
| `project_id`         | string  | Filter by project UUID                                 |
| `status`             | string  | Filter by status                                       |
| `ticket_source`      | string  | Filter by ticket source (e.g., `linear`, `jira`)       |
| `external_ticket_id` | string  | Filter by external ticket ID                           |
| `created_via`        | string  | Filter by creation method (e.g., `mcp`, `web`, `seed`) |
| `limit`              | integer | Max results to return                                  |

**Response:** Array of experiment objects with all ExperimentOps fields.

### Get Experiment

```
GET /api/v1.0/experiments/<experiment_id>
```

**Response:** Single experiment object with full detail including `source_type`, `source_ref`, `hypothesis`, `target_metric`, `observed_delta`, `delta_confidence`, `decision`, `tags`, `project_id`, `project_name`, `launch_context`, `ab_test_config`, `ab_test_results`, and linked resources.

### Update Experiment

```
PUT /api/v1.0/experiments/<experiment_id>
```

| Field                | Type   | Description                                                                                                   |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------- |
| `name`               | string | Experiment name                                                                                               |
| `status`             | string | Lifecycle state: `draft`, `running`, `complete`, `analyzing`, `shipped`, `iterating`, `rejected`, `abandoned` |
| `hypothesis`         | string | Hypothesis text                                                                                               |
| `outcome`            | string | `ship`, `iterate`, `abandon`                                                                                  |
| `decision`           | string | Decision text with reasoning                                                                                  |
| `observed_delta`     | float  | Measured metric change                                                                                        |
| `delta_confidence`   | string | `significant`, `inconclusive`, `not_tested`                                                                   |
| `target_metric`      | string | Target business metric                                                                                        |
| `tags`               | array  | Free-form tags for grouping                                                                                   |
| `pr_url`             | string | Link to implementation PR                                                                                     |
| `pr_status`          | string | PR status                                                                                                     |
| `external_ticket_id` | string | Linked external ticket ID                                                                                     |
| `ticket_source`      | string | Ticket provider                                                                                               |
| `ticket_url`         | string | Ticket URL                                                                                                    |

***

## Implementation

Manage the experiment implementation pipeline — context assembly, implementation runs, and status tracking.

### Get Experiment Context

```
GET /api/v1.0/implement/experiments/<experiment_id>/context
```

Returns the full experiment context formatted for Claude Code: resource metadata, Docker environment, task description, and implementation plan.

### Get Reference Implementation

```
GET /api/v1.0/implement/experiments/<experiment_id>/reference
```

Returns reference implementation sources: GitHub repo, Docker image, key methods, and implementation plan extracted from the launch context.

### List Actionable Experiments

```
GET /api/v1.0/implement/experiments/actionable
```

| Parameter    | Type    | Description            |
| ------------ | ------- | ---------------------- |
| `project_id` | string  | Filter by project UUID |
| `limit`      | integer | Max results            |

Returns experiments that have a `launch_context` but no PR yet — ready for implementation.

### Run Implementation

```
POST /api/v1.0/implement/experiments/<experiment_id>/run
```

Triggers the server-side implementation pipeline. Returns `202 Accepted` with a task reference.

### Get Implementation Status

```
GET /api/v1.0/implement/experiments/<experiment_id>/status
```

Returns the current pipeline status: `pipeline_status`, `pr_url`, `pr_status`, and timing information.

### Report Implementation Result

```
POST /api/v1.0/implement/experiments/<experiment_id>/report
```

| Field         | Type   | Description                    |
| ------------- | ------ | ------------------------------ |
| `pr_url`      | string | URL of the created PR          |
| `branch_name` | string | Git branch name                |
| `summary`     | string | Implementation summary         |
| `status`      | string | Result status                  |
| `artifacts`   | object | Additional artifact references |

***

## Research Interests

Manage your Research Interests — the context that drives personalized resource recommendations.

<Note>
  Two interests surfaces exist. The token/programmatic API uses **`/interests`** (documented here). The session/web app uses `/research-interests`. When calling with an API key, always use `/interests`.
</Note>

### List Interests

```
GET /api/v1.0/interests
```

**Response:** Array of Research Interest objects with `name`, `context`, `daily_count`, `is_active`.

### Create Interest

```
POST /api/v1.0/interests
```

| Field         | Type    | Required | Description                                             |
| ------------- | ------- | -------- | ------------------------------------------------------- |
| `name`        | string  | Yes      | Interest label (e.g., "Retrieval-Augmented Generation") |
| `context`     | string  | Yes      | URLs and descriptions defining the interest             |
| `daily_count` | integer | No       | Recommendations per day (default: 3)                    |
| `is_active`   | boolean | No       | Whether the interest is active (default: true)          |

### Get Interest

```
GET /api/v1.0/interests/<interest_id>
```

**Response:** The full interest object. Includes an additive `experiment_history` field, a bullet list summarizing the experiments linked to this interest.

### Update Interest

```
PUT /api/v1.0/interests/<interest_id>
```

Accepts same fields as Create. Updating `context` invalidates the recommendation pool and triggers re-ranking.

### Delete Interest

```
DELETE /api/v1.0/interests/<interest_id>
```

Deletes the interest and cascading recommendations.

### Toggle Interest

```
POST /api/v1.0/interests/<interest_id>/toggle
```

Toggles the `is_active` status without deleting the interest or its history.

### Provision an Interest

```
POST /api/v1.0/interests/<interest_id>/provision
```

Kicks off provisioning of [automated discovery PRs](/platform/agents/outrider-action) (Outrider) for the interest: sets up the GitHub repo, injects an automation (`rmxa_`) key into repo secrets, and prepares the continuous-experimentation loop. Optional `agent` in the body (`claude` — the default — / `codex` / `backboard`) picks the [coding agent](/platform/agents/backends#the-agent-input) the rendered workflow runs; it's validated against the interest's model provider up front, so an impossible pair is a `400` rather than a `200` that renders the wrong agent. Requires the `provisioning:write` scope. Returns `202 Accepted` with a `task_id`.

```
GET /api/v1.0/interests/<interest_id>/provision/<task_id>
```

Polls a specific provisioning task started by the call above.

```
GET /api/v1.0/interests/<interest_id>/provision-status
```

Returns the current provisioning state for the interest (independent of any single task).

```
POST /api/v1.0/interests/<interest_id>/provision-cli-token
```

Mints a scoped CLI token for the provisioned environment. Requires the `provisioning:write` scope.

### Score Candidates

```
POST /api/v1.0/experiment-histories/<history_id>/score-candidates
```

Scores candidate experiments against the interest's preference model and returns ranked results.

### Refit Preference Model

```
POST /api/v1.0/experiment-histories/<history_id>/refit-preference-model
```

Re-fits the preference model for the experiment history from accumulated feedback. Returns `202 Accepted` with a task reference.

***

## Recommendations

Get personalized resource recommendations based on your Research Interests.

### List Recommendations

```
GET /api/v1.0/papers/recommended
```

| Parameter     | Type    | Description             |
| ------------- | ------- | ----------------------- |
| `interest_id` | string  | Filter by interest UUID |
| `limit`       | integer | Max results             |
| `period`      | string  | `today`, `week`         |

**Response:** Array of recommended resources with titles, abstracts, relevance scores, and links.

### Get Digest

```
GET /api/v1.0/papers/recommended/digest
```

| Parameter | Type    | Description              |
| --------- | ------- | ------------------------ |
| `limit`   | integer | Max results per interest |
| `period`  | string  | `today`, `week`          |

**Response:** Structured digest grouped by Research Interest.

### Refresh Recommendations

```
POST /api/v1.0/papers/recommended/refresh
```

| Field         | Type    | Description                                                       |
| ------------- | ------- | ----------------------------------------------------------------- |
| `interest_id` | string  | Refresh a specific interest (optional — refreshes all if omitted) |
| `num_results` | integer | Number of results to generate                                     |

Returns `202 Accepted` with a task reference for polling.

### Poll Refresh Status

```
GET /api/v1.0/papers/recommended/refresh/<task_id>
```

Returns the status of an async recommendation refresh task.

***

## Search

Search across research assets with hybrid retrieval.

### Search Assets

```
POST /api/v1.0/search/assets
```

| Field         | Type    | Description                                            |
| ------------- | ------- | ------------------------------------------------------ |
| `query`       | string  | Natural language search query                          |
| `max_results` | integer | Max results to return                                  |
| `has_docker`  | boolean | Filter for resources with runnable Docker environments |
| `categories`  | array   | Filter by categories                                   |
| `use_llm`     | boolean | Enable LLM-enhanced search                             |

**Response:** Array of matching assets with titles, abstracts, categories, Docker availability, and relevance scores.

### Get Asset Details

```
GET /api/v1.0/search/assets/<arxiv_id>
```

Returns detailed information for a specific asset: full abstract, Docker status, Dockerfile, reference summary.

### List Recent Assets

```
GET /api/v1.0/search/assets/list
```

| Parameter    | Type    | Description                    |
| ------------ | ------- | ------------------------------ |
| `limit`      | integer | Max results (default: 20)      |
| `offset`     | integer | Pagination offset              |
| `category`   | string  | Filter by category             |
| `has_docker` | boolean | Filter for Docker availability |

### Get Asset Statistics

```
GET /api/v1.0/search/stats
```

Returns aggregate statistics: total assets, counts by Docker availability, by category, and citation classification coverage.

***

## Integrations

Manage OAuth connections to external tools (GitHub, Linear, Jira).

### List Providers

```
GET /api/v1.0/integrations/providers
```

Returns available integration providers with configuration status.

### Get OAuth URL

```
GET /api/v1.0/integrations/<provider_name>/auth-url
```

Returns the OAuth authorization URL to initiate the connection flow.

### Exchange OAuth Code

```
POST /api/v1.0/integrations/<provider_name>/callback
```

| Field          | Type   | Description                        |
| -------------- | ------ | ---------------------------------- |
| `code`         | string | OAuth authorization code           |
| `redirect_uri` | string | Callback URI used in the auth flow |

### List Connections

```
GET /api/v1.0/integrations/connections
```

Returns all active integration connections for the current user.

### Check Connection Status

```
GET /api/v1.0/integrations/<provider_name>/status
```

### Disconnect Provider

```
DELETE /api/v1.0/integrations/<provider_name>
```

Deactivates the integration connection for the specified provider.

### Get OAuth Token

```
GET /api/v1.0/integrations/<provider_name>/token
```

Returns a valid OAuth token for the specified provider. Auto-refreshes expired tokens before returning. Accepts optional `user_id` query param for service tokens.

### Identity Resolution

```
GET /api/v1.0/integrations/identity/resolve
```

| Parameter        | Type   | Description                                       |
| ---------------- | ------ | ------------------------------------------------- |
| `source`         | string | External platform (e.g., `github`, `linear`)      |
| `external_id`    | string | External user ID                                  |
| `external_email` | string | External user email (alternative to external\_id) |

```
POST /api/v1.0/integrations/identity/link
```

Creates an identity link between a Remyx user and an external platform identity.

```
GET /api/v1.0/integrations/identity/links
```

Lists all identity links for the current user.

***

## Outrider agents

The [agent](/platform/agents/overview) plane: run telemetry, the fleet report, the inbox, and dispatch. Base path `/api/v1.0/outrider`. These endpoints back the studio's Agents, Reports, and Inbox views and the MCP fleet tools, so what you read here matches the app exactly. Visibility is scoped to your own agents.

### Runs & telemetry

```
POST /api/v1.0/outrider/runs
GET  /api/v1.0/outrider/runs
```

`POST /runs` is called by the [Outrider action](/platform/agents/outrider-action) itself (authenticated with the repo's provisioned agent key) to report per-run telemetry: cost identity (backend, model, tokens, cost basis), selection audit (pool sizes, per-candidate rejections, reasoning excerpt), routing and gate outcomes, chain phases, and file-touch lists. Idempotent on `run_id`.

`GET /runs` lists your runs; params `repo`, `limit` (default 20, max 100), and `include=selection` to add the selection audit trail.

```
POST /api/v1.0/outrider/agents/runs/analyze
```

Root-cause analysis of one run from its job log: `{repo, run_id}` → cause, evidence bullets, suggested next step. Cached per run.

### Fleet report, activity, and inbox

```
GET  /api/v1.0/outrider/agents/report
GET  /api/v1.0/outrider/agents/activity?repo=owner/name
GET  /api/v1.0/outrider/agents/inbox
POST /api/v1.0/outrider/agents/inbox/dismiss
POST /api/v1.0/outrider/agents/inbox/digest
POST /api/v1.0/outrider/agents/artifact/evidence
POST /api/v1.0/outrider/agents/refresh
POST /api/v1.0/outrider/agents/chat
```

* `/agents/report` — the [fleet report](/platform/review/reports): headline, KPIs, per-agent timelines and terminal states, findings, deliverable pipeline, chronology. `since`/`until` (YYYY-MM-DD) and `repos` (intersected with your own footprint — it can only narrow) scope it.
* `/agents/activity` — one agent's runs, events, directions, and summary; backs [Agent detail](/platform/agents/overview#the-agent-report).
* `/agents/inbox` — the derived [Inbox](/platform/review/inbox); `inbox/dismiss` archives `{id}` or `{ids: […]}` (or `undo: true`), `inbox/digest` generates-once-and-persists the TLDR digest for a PR/Issue `{href}`, and `artifact/evidence` returns the deterministic gate/fidelity facts for one artifact.
* `/agents/refresh` — force a re-fetch of agent state from GitHub (`{full: false}` for a delta).
* `/agents/chat` — one stateless turn of run-grounded chat: `{repo, messages[], focus_run_id?}`; context is assembled server-side, and the transcript carries no privileged access.

### Installations & dispatch

```
GET  /api/v1.0/outrider/installations
POST /api/v1.0/outrider/installations/<id>/revoke
POST /api/v1.0/outrider/trigger
GET  /api/v1.0/outrider/run-status?repo=owner/name
```

* `/installations` — one row per provisioned agent, including paused (revoked) ones.
* `/installations/<id>/revoke` — **pause an agent**: marks the installation revoked and revokes its agent key, so the next run fails auth immediately.
* `/trigger` — the API twin of `remyxai outrider trigger`: `{repo, pin_arxiv?, interest_id?, ref?, agent?, provider?, model?, start_from_ref?, lead_content?, test_integration_policy?, fidelity_policy?}`. `agent` (`claude` / `codex` / `backboard`) is validated against `provider` before dispatch — an impossible pair is a `400`, and the credential the run is armed with follows the pair rather than whatever key the account has connected. Dispatches via the remyx\[bot] App token; returns `409 {pool_building: true}` while a fresh interest's candidate pool is still building.
* `/run-status` — the latest run for a repo, live from GitHub (no webhook lag), enriched with its outcome kind and artifact URL.

<Note>
  Outcome tracking (merge/close of the artifacts a run opened) is **webhook-driven** — it flows back through the GitHub webhooks rather than being polled here.
</Note>

***

## GitHub App & Provisioning

Endpoints for installing the Remyx GitHub App and provisioning repos for [automated discovery PRs](/platform/agents/outrider-action) (Outrider). The per-interest provisioning endpoints live under [Research Interests](#research-interests).

### Get Install URL

```
GET /api/v1.0/github/app/install-url
```

Returns the URL to install the Remyx GitHub App on a user's account or org.

### Get Installation

```
GET /api/v1.0/github/app/installation?repo=owner/name
```

| Parameter | Type   | Description                     |
| --------- | ------ | ------------------------------- |
| `repo`    | string | Repository in `owner/name` form |

Returns the GitHub App installation that covers the given repo (if any).

### Get Installation Token

```
POST /api/v1.0/github/installation-token
```

Mints a short-lived GitHub App installation token for the target repo. Scope-gated; requires `github:write`.

| Field  | Type   | Description                     |
| ------ | ------ | ------------------------------- |
| `repo` | string | Repository in `owner/name` form |

### Fork a Repo

```
POST /api/v1.0/github/fork
```

Forks a repo into **your own account** (your identity, never the bot's), optionally seeding `branches` from the source network — this is what the Quickstart's set-example track uses to warm-start curated drafts. Idempotent.

| Field      | Type   | Description                                   |
| ---------- | ------ | --------------------------------------------- |
| `repo`     | string | Repository in `owner/name` form               |
| `branches` | array  | Branch names to seed into the fork (optional) |

***

## Eval Environments

Build and run containerized evaluation environments. Base path `/api/v1.0/eval-env`.

### Builds

```
POST /api/v1.0/eval-env/builds
GET  /api/v1.0/eval-env/builds/<build_id>
GET  /api/v1.0/eval-env/builds/<build_id>/context
POST /api/v1.0/eval-env/builds/<build_id>/report
```

`POST /builds` starts a new environment build. `GET /builds/<id>` returns build status; `/context` returns the assembled build context; `POST /builds/<id>/report` reports the build result back from a worker.

### Runs

```
GET  /api/v1.0/eval-env/runs
POST /api/v1.0/eval-env/runs
GET  /api/v1.0/eval-env/runs/<run_id>
POST /api/v1.0/eval-env/runs/<run_id>/cancel
```

List or create eval runs, fetch a single run, or cancel an in-flight run.

### Templates

```
POST /api/v1.0/eval-env/templates
GET  /api/v1.0/eval-env/templates
GET  /api/v1.0/eval-env/templates/<template_id>
PUT  /api/v1.0/eval-env/templates/<template_id>
POST /api/v1.0/eval-env/templates/<template_id>/lock
```

CRUD for reusable eval-environment templates. `POST /templates/<id>/lock` freezes a template so it can't be edited once it's in use.

### Result Webhooks

```
POST /api/v1.0/eval-env/webhooks/results
POST /api/v1.0/eval-env/webhooks/modal/results
```

Inbound webhooks that deliver eval results back to Remyx: `webhooks/results` for the generic path and `webhooks/modal/results` for Modal-hosted runs.

***

## Authentication

All API requests require an opaque API key passed as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer rmxu_xxxxxxxxxxxxxxxxxxxxxxxx" \
  https://engine.remyx.ai/api/v1.0/experiments
```

Keys come in two flavors, distinguished by prefix:

| Prefix   | Type       | Typical use                                           |
| -------- | ---------- | ----------------------------------------------------- |
| `rmxu_…` | Personal   | CLI, MCP, ad-hoc REST calls (no expiry)               |
| `rmxa_…` | Automation | Outrider provisioning, CI, repo secrets (365-day TTL) |

Each key carries a set of **scopes** that gate which routes it can call (a route returning `403` means the key lacks the required scope). See [API Scopes](/api-reference/scopes) for the full catalog, presets, and which surface needs what.

Create and manage named keys at **Account > API keys** in the Remyx app, or programmatically:

```
GET    /api/v1.0/account/api-keys          # list keys (+ scope catalog & presets)
POST   /api/v1.0/account/api-keys          # create (plaintext returned once)
PATCH  /api/v1.0/account/api-keys/<id>     # rename / edit scopes (agent keys: rename only)
POST   /api/v1.0/account/api-keys/<id>/revoke
DELETE /api/v1.0/account/api-keys/<id>
POST   /api/v1.0/account/delete            # delete the account: revokes every key, disconnects integrations
```

Revoking an agent (`rmxa_`) key **pauses the agent that uses it**. See [Account & keys](/platform/configure/account).

<Warning>
  The legacy single-token endpoints under `/account/tokens/*` are removed and now return `410 Gone`. Migrate to named keys via `/account/api-keys`.
</Warning>

### Response Codes

| Code  | Meaning                                                              |
| ----- | -------------------------------------------------------------------- |
| `200` | Success                                                              |
| `201` | Created                                                              |
| `202` | Accepted (async task started)                                        |
| `400` | Bad request (invalid parameters)                                     |
| `401` | Unauthorized (missing or invalid token)                              |
| `403` | Forbidden (key lacks the required scope)                             |
| `404` | Not found                                                            |
| `409` | Conflict (e.g., duplicate resource)                                  |
| `410` | Gone (legacy `/account/tokens/*` endpoints; use `/account/api-keys`) |
| `500` | Server error                                                         |