# Systematic Reviews: agent API guide

Guide version: 1.0.0. Verified against Publishing frontend 0.21.2, review service 0.27.2 and local CLI 0.2.1.

Workspace: https://conductscience.org/systematic-reviews

An external agent such as Codex or Claude can prepare a protocol and use the HTTP API to save work in its owner's account. The website stores the shared record, versions, evidence and approvals. It does not start a hosted autonomous agent merely because a draft exists.

## Connect an agent

Production API base: https://conductscience.org/review-api

Every authenticated request uses `Authorization: Bearer <agent-key>` and `x-cms-tenant: conductscience`. JSON writes also use `Content-Type: application/json`. Keep the key in the agent's secret storage, outside protocol files, source control and browser JavaScript.

A Publishing operator currently provisions an expiring, revocable `csr_key_` credential for the existing review account. There is no self-service agent-key screen yet. The administrative credential endpoint exists internally but is intentionally absent from the public proxy; an agent cannot issue itself a key. A key is scoped to a tenant and account, not to one specific review, so grant only the operations needed and revoke it after the task. Do not substitute a researcher's password or human-session token.

Available credential scopes:

| Scope | Use |
| --- | --- |
| `review_registration:draft:create` | Create an owned draft |
| `review_registration:draft:read` | Read owned drafts and permitted review inventories |
| `review_registration:draft:update` | Revise editable protocols and submit permitted workflow proposals |
| `review_registration:draft:validate` | Check a protocol and request owner attestation |
| `review_registration:status:read` | Read the review event history |

The account that owns a record is separate from its author/contributor list. Preserve both when updating a draft. Account names and emails are private metadata, not public author identifiers.

## Find and update the shared draft

All paths below are relative to the API base. Responses put the result in `data`.

| Request | Purpose |
| --- | --- |
| `GET /v1/review-registrations` | Find the account's most recent owned records before creating another |
| `POST /v1/review-registrations` | Create with `{ "clientRequestId": "stable-task-id", "protocol": { ... } }` and a stable `Idempotency-Key` header |
| `GET /v1/review-registrations/{draftId}` | Read the current `version.protocol`, `version.payload_sha256`, status and `lock_version` |
| `PATCH /v1/review-registrations/{draftId}` | Send `{ "protocol": { ... }, "expectedLockVersion": 1 }`, using the actual current lock version |
| `POST /v1/review-registrations/{draftId}/validate` | Run the server's schema and policy checks |
| `POST /v1/review-registrations/{draftId}/request-attestation` | Request owner review after validation passes; this is not approval |
| `GET /v1/review-registrations/{draftId}/events` | Read the event history with the status scope |

On a create retry, reuse the same request ID, idempotency key and exact payload. On `409 VERSION_CONFLICT`, fetch the latest draft and reconcile changes instead of blindly overwriting it. Human-approved versions are frozen; agents cannot revise them in place. Read the record back after a write and retain the returned version/hash in the task log.

This read-only example uses Python's standard library. Supply an operator-issued key in `CS_REVIEW_AGENT_KEY`; it prints only record IDs and statuses:

```python
import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://conductscience.org/review-api/v1/review-registrations",
    headers={
        "Authorization": "Bearer " + os.environ["CS_REVIEW_AGENT_KEY"],
        "x-cms-tenant": "conductscience",
    },
)
with urlopen(request, timeout=30) as response:
    records = json.load(response)["data"]
for record in records:
    print(record["draft_id"], record["status"])
```

Open a saved record in the browser using `https://conductscience.org/systematic-reviews?draft=` followed by its returned UUID. The signed-in owner and the agent work with the same saved record.

## Work after registration

The hosted execution pipeline requires a registered protocol and the preceding evidence stages. Agents with the read/update scopes can use these routes as their prerequisites are satisfied:

| Work | Read | Submit |
| --- | --- | --- |
| Search imports | `GET /v1/review-registrations/{draftId}/search-imports` | `POST /v1/review-registrations/{draftId}/search-imports` |
| Screening | `GET /v1/review-registrations/{draftId}/screening` | `POST /v1/review-registrations/{draftId}/screening-decisions` |
| Extraction | `GET /v1/review-registrations/{draftId}/extraction` | `POST /v1/review-registrations/{draftId}/extractions` |
| Appraisal | `GET /v1/review-registrations/{draftId}/appraisals` | `POST /v1/review-registrations/{draftId}/appraisals` |
| Analysis and certainty | `GET /v1/review-registrations/{draftId}/synthesis` | `POST /v1/review-registrations/{draftId}/synthesis-runs` and `/certainty-assessments` |
| Manuscript preparation | `GET /v1/review-registrations/{draftId}/manuscript` | `POST /v1/review-registrations/{draftId}/manuscript-versions` and `/manuscript-reviews` |

Use the exact request schemas in the source routes rather than inventing fields: https://github.com/ShuhanCS/conductscience-publishing/blob/main/science-cms/src/registrations/routes.ts

Extraction and appraisal proposals retain source locations and quotes. Analysis proposals retain their inputs, results and version information. An agent cannot finalize extraction, appraisal, synthesis or certainty, attest to a protocol, approve a manuscript, adjudicate conflicts, or confirm a final full-text exclusion. Those operations require a human session; protocol approval requires the named owner and the exact document hash. Distinct agent credentials distinguish submissions but do not establish independent human review.

The hosted analysis engine supports generic pairwise inverse-variance meta-analysis. It does not execute arbitrary uploaded code or reproduce Diagnostic Information's bivariate diagnostic-accuracy model. Specialized analyses can run in the research repository and be archived with their code, inputs and results.

## Local preparation

The repository includes a local CLI for protocol preparation, validation, verification reports and document packages. It does not authenticate or synchronize with the hosted account API; use HTTP for that step.

```sh
node reviews-cli/src/conduct.mjs --help
node reviews-cli/src/conduct.mjs reviews validate review-protocol.json
```

Schema: https://github.com/ShuhanCS/conductscience-publishing/blob/main/reviews-cli/schemas/systematic-review-protocol.schema.json

CLI: https://github.com/ShuhanCS/conductscience-publishing/blob/main/reviews-cli/src/conduct.mjs

## Completed studies, Zenodo and preprints

For work already completed, document the actual methods and dates in the protocol record and link the existing outputs. Do not replay research solely to populate the hosted pipeline, or mark it externally registered to unlock a stage. An internal protocol date and a later public archive date describe different events.

The planned relationship is:

- ConductScience: study record, methods history and links to outputs.
- Zenodo: archived data, analysis code, results, environment and reproduction instructions.
- Preprint server: the manuscript and supplement, citing supporting records.
- Journal: the eventual published article, with its own DOI.

Direct Zenodo and preprint submission are not implemented here. Agents can prepare files and metadata for the chosen destination. Record reserved, uploaded, submitted and published states accurately; provider confirmation establishes the public URL and DOI. External upload/publication requires its own authenticated provider workflow and author authorization. The existing OSF workflow also requires owner completion and verification before reporting public registration.