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.

POST /v2/workflow/steps/recordAgentResolution

Record Agent Resolution

cURL

curl --request POST \
  --url https://api.velt.dev/v2/workflow/steps/recordAgentResolution \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "executionId": "<string>",
    "stepId": "<string>",
    "resolutionId": "<string>",
    "status": "<string>",
    "output": {},
    "errorMessage": "<string>"
  }
}
'

import requests

url = "https://api.velt.dev/v2/workflow/steps/recordAgentResolution"

payload = { "data": {
        "executionId": "<string>",
        "stepId": "<string>",
        "resolutionId": "<string>",
        "status": "<string>",
        "output": {},
        "errorMessage": "<string>"
    } }
headers = {
    "x-velt-api-key": "<x-velt-api-key>",
    "x-velt-auth-token": "<x-velt-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-velt-api-key': '<x-velt-api-key>',
    'x-velt-auth-token': '<x-velt-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      executionId: '<string>',
      stepId: '<string>',
      resolutionId: '<string>',
      status: '<string>',
      output: {},
      errorMessage: '<string>'
    }
  })
};

fetch('https://api.velt.dev/v2/workflow/steps/recordAgentResolution', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.velt.dev/v2/workflow/steps/recordAgentResolution",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'data' => [
        'executionId' => '<string>',
        'stepId' => '<string>',
        'resolutionId' => '<string>',
        'status' => '<string>',
        'output' => [
                
        ],
        'errorMessage' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-velt-api-key: <x-velt-api-key>",
    "x-velt-auth-token: <x-velt-auth-token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.velt.dev/v2/workflow/steps/recordAgentResolution"

	payload := strings.NewReader("{\n  \"data\": {\n    \"executionId\": \"<string>\",\n    \"stepId\": \"<string>\",\n    \"resolutionId\": \"<string>\",\n    \"status\": \"<string>\",\n    \"output\": {},\n    \"errorMessage\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-velt-api-key", "<x-velt-api-key>")
	req.Header.Add("x-velt-auth-token", "<x-velt-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.velt.dev/v2/workflow/steps/recordAgentResolution")
  .header("x-velt-api-key", "<x-velt-api-key>")
  .header("x-velt-auth-token", "<x-velt-auth-token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"data\": {\n    \"executionId\": \"<string>\",\n    \"stepId\": \"<string>\",\n    \"resolutionId\": \"<string>\",\n    \"status\": \"<string>\",\n    \"output\": {},\n    \"errorMessage\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.velt.dev/v2/workflow/steps/recordAgentResolution")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-velt-api-key"] = '<x-velt-api-key>'
request["x-velt-auth-token"] = '<x-velt-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"data\": {\n    \"executionId\": \"<string>\",\n    \"stepId\": \"<string>\",\n    \"resolutionId\": \"<string>\",\n    \"status\": \"<string>\",\n    \"output\": {},\n    \"errorMessage\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "result": {
    "recorded": true,
    "aggregatorStatus": "resolved",
    "resumeScheduled": true
  }
}

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

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

executionId · string · required

The execution containing the step.

stepId · string · required

Must reference a blocking agent step in waiting.

resolutionId · string · required

^[A-Za-z0-9:_\-.]{1,200}$. Stable identifier per logical resolution (idempotent across replays).

status · string · required

success / failure.

output · object

Agent output. Capped (each value ≤ 16k chars).

errorMessage · string

Required when status === "failure".

Example Requests

Successful resolution

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

Response

Success Response

{
  "result": {
    "recorded": true,
    "aggregatorStatus": "resolved",
    "resumeScheduled": true
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "FAILED_PRECONDITION"
  }
}

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

{
  "result": {
    "recorded": true,
    "aggregatorStatus": "resolved",
    "resumeScheduled": true
  }
}