Run an Agent Through the API
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.
Before you start
Section titled “Before you start”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.
Submit an input
Section titled “Submit an input”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.
Continue and supply Knowledge
Section titled “Continue and supply Knowledge”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.
Retrieve the result
Section titled “Retrieve the result”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.
Troubleshooting
Section titled “Troubleshooting”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.