Skip to main content
POST
Ask the Architect to fix a failed run
The reference panel describes the current v3 operation. The notes below describe its v2 compatibility API. Follow the v3 request schema for current calls: v3 can move identifiers from the body or query into the URL. Keep the v2 method, path, and payload together when using the compatibility API.

v2 compatibility notes

POST /api/v2/workflows/askArchitectToFixRun The API twin of the Console’s Fix with Architect. When the run’s workflow has no draft, a draft is cloned from the run’s pinned version, its Architect conversation is opened, and the earliest failed step and its error are seeded into it (mode: "new_draft"). When the workflow has a draft, the failure is added to the draft’s open Architect conversation (mode: "appended"). A new draft’s conversation names its caller as the person who decides the Architect’s plans and synthesis batches, so only a Personal key opens one. An External App or a platform key may append to an existing conversation; for a workflow without a draft it answers 403 with personRequired: true. No Architect turn runs. The Architect reads the failure on the conversation’s next turn, which a person starts by sending a message in the Forge Console.

Authentication

Personal key, External App credential or platform API key. Requires permission workflows:write, and workflows:write and workflows:read held at the run’s workflow’s home org unit. A run that carries companies also needs runs:read at each of them, because its failure is copied into the conversation. The new draft and the seeded failure are attributed to a Personal key’s owner, else to the calling app or key.

Headers

string
Optional. A same-key retry within 24 hours returns the recorded answer without writing again, only while the caller may still write the draft of the workflow that answer names, at that workflow’s home; otherwise 409 idempotency_result_unavailable. The same key with a different body is 422. See Idempotency.

Body

string
required
The failed run’s ID.

Responses

201 with:
string
The run’s workflow.
string
The draft the failure was opened in.
string
new_draft or appended.

Errors

Example

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

Optional logical intent key. A same-key retry within 24 hours returns the recorded result without writing again.

Required string length: 1 - 255

Path Parameters

runId
string
required

The failed run's id.

Minimum string length: 1

Response

Ask the Architect to fix a failed run

data
object
required
meta
object
required