> ## Documentation Index
> Fetch the complete documentation index at: https://velt-mintlify-e6426361.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Record agent resolution (v2)

> Submit an AI agent's resolution for an approval step using the Velt v2 REST API to record agent verdicts, confidence, and reasoning back into the run.

Use this API to record an external resolution for a **blocking** agent step. The agent step parks in `waiting` after dispatch; resolutions arriving through this endpoint advance the aggregator according to its `resolutionPolicy` (`allResolved` or `minResolved`).

# Endpoint

`POST https://api.velt.dev/v2/workflow/steps/recordAgentResolution`

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="executionId" type="string" required>
      The execution containing the step.
    </ParamField>

    <ParamField body="stepId" type="string" required>
      Must reference a blocking agent step in `waiting`.
    </ParamField>

    <ParamField body="resolutionId" type="string" required>
      `^[A-Za-z0-9:_\-.]{1,200}$`. Stable identifier per logical resolution (idempotent across replays).
    </ParamField>

    <ParamField body="status" type="string" required>
      `success` / `failure`.
    </ParamField>

    <ParamField body="output" type="object">
      Agent output. Capped (each value ≤ 16k chars).
    </ParamField>

    <ParamField body="errorMessage" type="string">
      Required when `status === "failure"`.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### Successful resolution

```JSON theme={null}
{
  "data": {
    "executionId": "exec_1777374504255_xzy43k9q",
    "stepId": "step_blocking-agent_...",
    "resolutionId": "res_42",
    "status": "success",
    "output": { "summary": "Generated draft v3", "wordCount": 287 }
  }
}
```

# Response

#### Success Response

```JSON theme={null}
{
  "result": {
    "recorded": true,
    "aggregatorStatus": "resolved",
    "resumeScheduled": true
  }
}
```

#### Failure Response

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "FAILED_PRECONDITION"
  }
}
```

**Errors:** `FAILED_PRECONDITION` (step not waiting or not blocking) / `INVALID_ARGUMENT` / `NOT_FOUND`.

<ResponseExample>
  ```js theme={null}
  {
    "result": {
      "recorded": true,
      "aggregatorStatus": "resolved",
      "resumeScheduled": true
    }
  }
  ```
</ResponseExample>