Skip to content
API Reference

Run an Agent Through the API

Version: unreleased · Docs: 3c6ab9f2Download Markdown

Use POST /api/v1/agents/AGENT_ID/runs to run an agent you set up in Redbelt. HTTP 202 means Redbelt accepted the request; the answer arrives later.

Complete the API quickstart. Create and configure the agent in Redbelt, then share it with the identity behind your API key. A service key runs as its service user. Access granted to the human who created the key is insufficient. The organization needs a configured provider and available budget.

Call GET /api/v1/agents to discover accessible agents and GET /api/v1/agents/AGENT_ID to read the selected definition’s name and description. Set REDBELT_AGENT_ID to its UUID. Each request needs a UUIDv7 request_id; this example uses Python 3.14, whose standard library can generate one. On older versions, use any UUIDv7 library.

Save this as start_conversation.py:

"""Submit a UI-created agent; retain request_id for an exact retry."""

import json
import os
from urllib.request import Request, urlopen
from uuid import uuid7

api_url = os.environ.get("REDBELT_API_URL", "https://redbelt.ai/api").rstrip("/")
agent_id = os.environ["REDBELT_AGENT_ID"]
request_id = str(uuid7())
payload = {"request_id": request_id, "input": "Turn these project notes into a short action checklist.", "model": "auto"}
# Persist request_id and this exact payload before sending. A timeout does not
# mean rejection: retry this payload with the same ID, never a new UUID.
request = Request(
    f"{api_url}/v1/agents/{agent_id}/runs",
    data=json.dumps(payload).encode(),
    headers={"Authorization": f"Bearer {os.environ['REDBELT_API_KEY']}", "Content-Type": "application/json"},
    method="POST",
)
with urlopen(request, timeout=60) as response:
    submitted = json.load(response)
print(json.dumps(submitted, indent=2))
print("Status:", f"{api_url}/v1/executions/agent/{submitted['id']}")

Run python3 start_conversation.py. Save the returned id and thread_id. The id identifies your input; run_id appears once the agent starts working on it. A request ID belongs to its thread, so retry with the same ID and the same thread_id. The same ID on a different thread counts as a new input.

For reliable retries, save the generated request_id and exact request body before sending. Reuse them after a timeout. Running the example again generates a new request and can perform the work again.

Send a fresh UUIDv7 request_id, the returned thread_id, and only the new input to the same agent submission endpoint. Redbelt retains thread history. Use model: “auto” for normal agent model selection, or an available model slug.

Optional upload_ids and folder_ids contain UUIDs of Knowledge that this identity can access. Share required resources with a service user before submitting; sharing an agent does not share its author’s private documents or third-party credentials. Configure plugin access on the agent in Redbelt.

Call GET /api/v1/executions/agent/EXECUTION_ID. Inspect status, output, wait_id, and error_code. Add ?wait=30 to wait for the next status. For artifacts, questions, approvals and cancellation, follow Track Runs and Retrieve Results.

For a key owned by your human user, you can also open /thread/THREAD_ID in Redbelt while signed in as that same owner. Threads created by a service user remain owned by that identity; retrieve their results through its API key. The key’s creator-sharing setting does not grant access to these threads.

A 404 can mean an inaccessible agent or thread. A 409 can mean the same request ID was reused with changed input. A run accepted earlier can fail later because permissions, connections, budget or provider availability changed. Read its status before deciding to submit another request.