---
title: "Run an Architect turn (Responses)"
method: POST
path: "/api/v1/responses"
tags: ["Architect"]
---

# Run an Architect turn (Responses)

`POST /api/v1/responses`

## Request

- Base URL: `https://editor.pascal.app`
- URL: `https://editor.pascal.app/api/v1/responses`
- Auth: HTTP bearer

OpenAI Responses over one turn of the Architect on a project, with the same authentication, project header, models and files as chat completions. `input` is a string or message items, with `input_text`, `input_image` and `input_file` parts; `instructions` are instructions for this turn. The output is the reply as `message` items and the readable reasoning as `reasoning` items with `summary_text` parts. A turn that changed the scene is saved as one named version: `metadata.pascal_version`, `pascal_version_label` and `pascal_version_url`, and a `url_citation` annotation at the end of the reply. A turn that asked a question has `metadata.pascal_waiting: "question"`; the next request answers it (`1`, `2`… picks an option). `metadata.commit_message` names the version; `metadata.pascal_max_credits` caps the credits the turn may spend, and a turn that reaches it ends `incomplete` (`incomplete_details.reason: "max_credits"`). `previous_response_id` continues the project’s conversation and must belong to the project’s active conversation. With `stream: true` the response is a `text/event-stream` of Responses events (`response.created` through `response.completed`, `response.incomplete` or `response.failed`), with `: keepalive` comments during silences. Without `stream`, the headers leave within 15 s and spaces keep the connection open until the JSON body. A turn that fails after it started answers 200 with `status: "failed"` (`"cancelled"` once stopped): it is never retried, since it may already have edited the scene. A synchronous request follows its turn for at most 13 minutes: a turn still running then is stopped (`status: "failed"`), except an architect-pro turn, which runs on and answers `status: "in_progress"` (a stream ends with an `error` event, `turn_still_running`): poll `GET /api/v1/responses/{id}`. A turn that may run longer is sent with `background: true`, at any model: the request answers `status: "queued"` at once, the turn runs to its end with nobody following (credits charged and the version saved as for a followed turn), and `GET /api/v1/responses/{id}` reads it; `POST /api/v1/responses/{id}/cancel` stops it.

## Headers

- `X-Pascal-Project` string

## Request body

- ArchitectResponseRequest
  - `model` 'architect' | 'architect-low' | 'architect-medium' | 'architect-high' | 'architect-pro', required
  - `input` union, required: A string, or message items (`{ role, content }`).
    - string
    - object[]
      - `role` string
      - `content` union
        - string
        - ArchitectContentPart[]
          - `type` string, required
  - `instructions` string
  - `previous_response_id` string
  - `reasoning` object
    - `effort` 'minimal' | 'low' | 'medium' | 'high' | 'pro'
  - `stream` boolean
  - `background` boolean: Return at once (`status: "queued"`) and run the turn with nobody following; poll `GET /api/v1/responses/{id}`. Any model.
  - `metadata` object: Echoed on the response. `project_id` is an alternative to the `X-Pascal-Project` header; `pascal_max_credits` caps the credits the turn may spend.
    - `project_id` string
    - `pascal_max_credits` string: The most Pascal credits this turn may spend, a number above 0 sent as a string like every metadata value. No cap when absent; an invalid value is a 400. When the turn reaches it, it ends `incomplete` with `incomplete_details.reason: "max_credits"` (chat: `finish_reason: "length"`), and what it changed so far is saved as a version as usual. An architect-pro turn admits a model call only if its worst case fits under the cap, so its model calls never take it over; the time of the sandbox running its tools is billed after the fact and can. Every other turn is checked between its rounds of scene tools: once it has spent the cap it stops before the next round, so it can end above the cap by what its last round of model steps cost. A request that answers a question continues the turn under the cap the turn started with.

## Response `200`

Response object, or a server-sent event stream when `stream` is true

- ArchitectResponse
  - `id` string, required
  - `object` 'response', required
  - `created_at` integer
  - `status` 'queued' | 'in_progress' | 'completed' | 'incomplete' | 'failed' | 'cancelled', required
  - `model` string, required
  - `output` object[], required: `reasoning` items (`summary` of `summary_text` parts: the model’s thinking and one bold line per step) and `message` items (`output_text` with the version’s `url_citation` at the end).
  - `output_text` string
  - `error` object, nullable
    - `code` string
    - `message` string
    - `type` string
    - `param` string, nullable
  - `incomplete_details` object, nullable
    - `reason` 'balance' | 'max_credits' | 'time_limit': `balance`: the credit pool could not fund the next step; `max_credits`: the turn reached `metadata.pascal_max_credits`; `time_limit`: it ran out of time.
  - `metadata` ArchitectPascalMetadata: The turn’s outcome, beside the caller’s own string metadata: `pascal_project_id`; `pascal_version`, `pascal_version_label` and `pascal_version_url` when the turn saved a version; `pascal_waiting: "question"` when the next request answers the Architect’s question.
  - `usage` object, nullable

## Other responses

- `400`: OpenAI-shaped error, with `x-should-retry: false`: no error is retried. 400 invalid request, missing project, a file that can’t be sent, or `unsupported_parameter` (tools, structured output, `n` > 1) with its `param`; 401 invalid key; 403 `upgrade_required`; 404 unknown model, or project not found or not editable with this key; 409 `turn_in_progress` (naming the running `response_id`) or `previous_response_id` not on the project’s active conversation; 503 `executor_unavailable` on a deployment with no executor. The one retryable error is a `background` launch that failed before its turn ran (502, without the header).
- `401`: OpenAI-shaped error, with `x-should-retry: false`: no error is retried. 400 invalid request, missing project, a file that can’t be sent, or `unsupported_parameter` (tools, structured output, `n` > 1) with its `param`; 401 invalid key; 403 `upgrade_required`; 404 unknown model, or project not found or not editable with this key; 409 `turn_in_progress` (naming the running `response_id`) or `previous_response_id` not on the project’s active conversation; 503 `executor_unavailable` on a deployment with no executor. The one retryable error is a `background` launch that failed before its turn ran (502, without the header).
- `402`: The project’s credit pool (its workspace’s, else the key owner’s) cannot fund a turn. Returned before the turn starts, with `type` and `code` `insufficient_quota`.
- `404`: OpenAI-shaped error, with `x-should-retry: false`: no error is retried. 400 invalid request, missing project, a file that can’t be sent, or `unsupported_parameter` (tools, structured output, `n` > 1) with its `param`; 401 invalid key; 403 `upgrade_required`; 404 unknown model, or project not found or not editable with this key; 409 `turn_in_progress` (naming the running `response_id`) or `previous_response_id` not on the project’s active conversation; 503 `executor_unavailable` on a deployment with no executor. The one retryable error is a `background` launch that failed before its turn ran (502, without the header).
- `409`: OpenAI-shaped error, with `x-should-retry: false`: no error is retried. 400 invalid request, missing project, a file that can’t be sent, or `unsupported_parameter` (tools, structured output, `n` > 1) with its `param`; 401 invalid key; 403 `upgrade_required`; 404 unknown model, or project not found or not editable with this key; 409 `turn_in_progress` (naming the running `response_id`) or `previous_response_id` not on the project’s active conversation; 503 `executor_unavailable` on a deployment with no executor. The one retryable error is a `background` launch that failed before its turn ran (502, without the header).
- `503`: OpenAI-shaped error, with `x-should-retry: false`: no error is retried. 400 invalid request, missing project, a file that can’t be sent, or `unsupported_parameter` (tools, structured output, `n` > 1) with its `param`; 401 invalid key; 403 `upgrade_required`; 404 unknown model, or project not found or not editable with this key; 409 `turn_in_progress` (naming the running `response_id`) or `previous_response_id` not on the project’s active conversation; 503 `executor_unavailable` on a deployment with no executor. The one retryable error is a `background` launch that failed before its turn ran (502, without the header).

---

[API](https://skmtc.dev/pascal/apis/pascal-editor-scene-api.md) · [All operations](https://skmtc.dev/pascal/apis/pascal-editor-scene-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pascal/apis/pascal-editor-scene-api/revisions/08f1f3f41067?raw)