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

# Submit a Review Question

> POST /api/open/v1/projects/:projectId/reviews/:reviewId/messages — submits a text question and starts a durable review execution.

Submit one text question against the project's indexed sources. Your API key needs the `reviews:write` scope. Plangrep uses the existing durable review engine, server-selected model, token accounting, citation finalization, and current credit policy.

## Endpoint

```http theme={null}
POST https://plangrep.com/api/open/v1/projects/{projectId}/reviews/{reviewId}/messages
```

<ParamField header="Idempotency-Key" type="string" required>
  Client-generated key, up to 256 characters. Identical retries return the original execution.
</ParamField>

<ParamField body="body" type="string" required>
  Text question, from 1 to 524,288 characters and no more than 524,288 UTF-8 bytes after trimming. The complete JSON request body may be up to 4 MiB. Attachments, voice, and model options are not accepted.
</ParamField>

```bash theme={null}
curl -X POST https://plangrep.com/api/open/v1/projects/proj_abc/reviews/review_abc/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: envelope-question-1" \
  -H "Content-Type: application/json" \
  -d '{"body":"Summarize the air-barrier requirements and cite the sources."}'
```

The endpoint returns `202 Accepted` with the user `message`, durable `execution`, and `idempotent`. Connect to `execution.streamUrl` to receive public events over SSE or NDJSON. Use `execution.url` as the polling fallback. The execution status is initially `queued` or `running`; its terminal statuses are `completed`, `failed`, and `cancelled`.

```json theme={null}
{
  "execution": {
    "id": "review_execution_123",
    "status": "queued",
    "url": "/api/open/v1/projects/proj_abc/reviews/review_abc/executions/review_execution_123",
    "streamUrl": "/api/open/v1/projects/proj_abc/reviews/review_abc/executions/review_execution_123/stream"
  },
  "idempotent": false
}
```

See [Stream Review Execution](/api-reference/reviews/stream-execution) for Postman, replay, and event details.

Only one execution can be active in a review. A second turn returns `409 review_execution_active`.

## Errors

| HTTP          | Code                         | When it occurs                                                                                                           |
| ------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `400`         | `idempotency_key_required`   | The required `Idempotency-Key` header is missing.                                                                        |
| `400`         | `invalid_message`            | The message payload is invalid.                                                                                          |
| `402`         | `insufficient_credits`       | The project does not have enough review-token credits.                                                                   |
| `409`         | `idempotency_key_conflict`   | The key was previously used for a different submit-question request.                                                     |
| `409`         | `review_execution_active`    | Another execution is queued or running for this review.                                                                  |
| `409`         | `review_sources_unavailable` | Project sources cannot be used for review.                                                                               |
| `409`         | `review_sources_not_ready`   | Project sources have not finished ingestion and indexing.                                                                |
| `502` / `503` | —                            | The runtime response or durable execution start failed. Retry with the same idempotency key when the outcome is unclear. |