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

# Papers

> List papers in a lab and run the 5-round publish loop (Mechanical QA, Cross-Model Review, Houston Method, Format, arXiv Prep).

# Papers API

Papers are the long-form research artifacts your lab produces. The Papers API surfaces the lab's paper roster and exposes the 5-round publish loop that walks a draft from rough text to arXiv-ready submission.

Paper content (sections, figures, citations, draft history) lives in Convex and is read directly by the web app. The HTTP surface today covers two operations: listing papers for a lab, and triggering the publish loop on a paper that already exists.

## List Papers

Returns every paper in a lab.

<ParamField query="labId" type="string" required>
  Convex ID of the lab.
</ParamField>

<CodeGroup>
  ```bash curl theme={null}
  curl "https://www.hubify.com/api/v1/papers?labId=j57a8k9m2n3p4q5r" \
    -H "Authorization: Bearer $HUBIFY_TOKEN"
  ```

  ```typescript TypeScript SDK theme={null}
  const { papers, total } = await hubify.papers.list({
    labId: "j57a8k9m2n3p4q5r",
  });
  ```
</CodeGroup>

<ResponseField name="papers" type="object[]" required>
  Array of paper documents (Convex shape from `papers.listByLab`).
</ResponseField>

<ResponseField name="total" type="number" required>
  Number of papers returned.
</ResponseField>

### Auth and rate limiting

Requires an API key with read access to the lab. Subject to the read rate limit. Returns `400` if `labId` is missing, `403` if the key cannot access the lab.

## Run the Publish Loop

Runs the 5-round publish pipeline against an existing paper. The loop fans out reviews (one Claude review per round, plus a multi-model fan-out in round 2) and persists each review to the paper. Failures inside a round are recorded and the loop continues.

<ParamField path="id" type="string" required>
  Convex ID of the paper to run the loop against.
</ParamField>

<ParamField body="abstract" type="string" default="">
  Abstract text passed to each reviewer. If omitted, reviewers see an empty abstract (only useful for very early drafts).
</ParamField>

<ParamField body="rounds" type="number" default={5}>
  Number of rounds to run. Capped at 5. Use a smaller number to run an early stage in isolation (for example, `rounds: 2` to stop after the cross-model review).
</ParamField>

### Round map

| # | Name               | What runs                                                                                  |
| - | ------------------ | ------------------------------------------------------------------------------------------ |
| 1 | Mechanical QA      | Single Claude review checking structure, citations, figure references                      |
| 2 | Cross-Model Review | Multi-model fan-out (Claude + GPT + Gemini + Grok); each model files an independent review |
| 3 | Houston Method     | Single Claude review applying the Houston Method critique pass                             |
| 4 | Format Check       | Single Claude review for journal formatting and section ordering                           |
| 5 | arXiv Prep         | Single Claude review for arXiv submission readiness                                        |

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://www.hubify.com/api/v1/papers/p4q5r6s7t8u9v0w1/publish-loop" \
    -H "Authorization: Bearer $HUBIFY_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "abstract": "We present a Bayesian analysis of...",
      "rounds": 5
    }'
  ```

  ```typescript TypeScript SDK theme={null}
  const result = await hubify.papers.publishLoop({
    paperId: "p4q5r6s7t8u9v0w1",
    abstract: "We present a Bayesian analysis of...",
    rounds: 5,
  });
  ```
</CodeGroup>

<ResponseField name="paperId" type="string" required>
  The paper the loop ran against.
</ResponseField>

<ResponseField name="rounds" type="object[]" required>
  Per-round results, in execution order.

  <Expandable title="Round result">
    <ResponseField name="round" type="number" required>Round number (1-5).</ResponseField>
    <ResponseField name="name" type="string" required>Round name (e.g., `Cross-Model Review`).</ResponseField>
    <ResponseField name="status" type="string" required>`success` or `error`.</ResponseField>
    <ResponseField name="reviewCount" type="number">Number of reviews persisted in this round.</ResponseField>
    <ResponseField name="error" type="string">Error message when `status` is `error`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object" required>
  <Expandable title="Summary">
    <ResponseField name="total" type="number" required>Total rounds attempted.</ResponseField>
    <ResponseField name="success" type="number" required>Rounds that completed without error.</ResponseField>
    <ResponseField name="error" type="number" required>Rounds that errored.</ResponseField>
  </Expandable>
</ResponseField>

### Auth and rate limiting

Requires an API key with write access. Subject to the write rate limit. The loop runs synchronously: round 2 (multi-model fan-out) is the slowest stage. Expect total request time on the order of minutes, not seconds.

### Reading the reviews

The loop persists reviews to Convex; this endpoint returns counts, not review bodies. Read the actual review text from the paper detail view in the web app, or via the lab's `paperReviews` Convex query.

## Common Workflows

```bash theme={null}
# List drafts in flight, pick one, run a single QA round
curl "https://www.hubify.com/api/v1/papers?labId=$LAB_ID" \
  -H "Authorization: Bearer $HUBIFY_TOKEN" | jq '.papers[] | {id: ._id, title}'

curl -X POST "https://www.hubify.com/api/v1/papers/$PAPER_ID/publish-loop" \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"abstract": "...", "rounds": 1}'
```

```bash theme={null}
# Full publish gauntlet, all 5 rounds, then check the summary
curl -X POST "https://www.hubify.com/api/v1/papers/$PAPER_ID/publish-loop" \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"abstract": "...", "rounds": 5}' | jq '.summary'
```