Submit a Review Question

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

POST https://plangrep.com/api/open/v1/projects/{projectId}/reviews/{reviewId}/messages

Idempotency-Key

string

required

Client-generated key, up to 256 characters. Identical retries return the original execution.

body

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.

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.

{
  "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 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.

Projects

Jobs

Reviews

Uploads

Project Reads

Artifacts

Submit a Review Question

Endpoint

Errors

​Endpoint

​Errors

Endpoint

Errors