BoldAgent by Syncfusion has launched

Book a demo Free trial

Developer API

Build BoldAgent into your own apps

A versioned REST API for agents, libraries, decision models, MCP servers, guardrail policies, and conversations. Send a message and get the whole answer, stream it as it is written, or run it in the background.

Quick start API reference

Quick start

Your First Request in Three Steps

Create a key, add one header, and call the versioned base URL for your organization.

  1. 1 Create an API key Open the API keys section of your BoldAgent profile and select Create API key. Copy it right away: it is shown only once.
  2. 2 Add the header Send the key as X-API-Key: {yourapikey} or Authorization: ApiKey {yourapikey}, over HTTPS.
  3. 3 Call the API Use your organization’s domain with the versioned base path /developer-api/v1.0, then append the endpoint.
Your first request: list agents GET 
curl --request GET \
  "https://{yourdomain}/developer-api/v1.0/agents" \
  --header "X-API-Key: {yourapikey}" \
  --header "Accept: application/json"

What you can manage

The Platform, Programmatically

Manage the same resources you use in BoldAgent, so you can automate setup, sync content, and run agents from your own systems.

  • Agents and versions Create, update, and publish agent versions. Link libraries, MCP tools, and decision models, and manage AI context settings.
  • Libraries Create libraries, upload and re-upload files, and manage Q & A entries.
  • Web sources Add a site, review crawled pages, exclude pages, and re-sync a page or the whole source.
  • Decision models Create decision models, start from question templates, and publish versions.
  • MCP servers Register servers, including OAuth with callback and re-authentication, and list their tools.
  • Guardrail policies Create and update the policies that check what goes in and out of an agent.
  • Categories Organize agents, skills, and tools so they are easier to find.
  • Conversations Start conversations, get their details, and list them per agent or per end user.
  • Messages Send or stream messages, read chat history, and record feedback on answers.
  • Runs Submit background runs, stream their output, check status, or cancel them.
  • Attachments Upload files for a conversation, get their URLs, and remove them.
  • Sandbox environments List the environments available for sandbox code execution.

Talking to agents

Three Ways to Get an Answer

Choose the one that fits how your application waits. Leave out the conversation ID and a new conversation starts automatically.

Wait for the whole answer

Send a message and receive the complete answer in a single response. The simplest option when your application can wait.

  • One request, one complete answer
  • A new conversation starts if you leave out the conversation ID
POST /agents/{agentId}/conversations/messages Send Message

Show the answer as it is written

Send a message and stream the answer as server-sent events (text/event-stream) while it is generated. The request body is the same as Send Message.

  • Answer arrives word by word
  • Best for chat interfaces
POST /agents/{agentId}/conversations/messages/stream Stream Message

Run it in the background

Submit the message as a run and get its details back right away. Follow the run by streaming its output or checking its status, and cancel it if it is no longer needed. Choose stream or non-stream with responseMode.

  • Stream the run output until it completes
  • Cancel a run that is still in progress
POST /agents/{agentId}/conversations/runs Submit Run
GET /…/runs/{runId}/stream Stream Run
GET /…/runs/{runId} Get Run Status
PATCH /…/runs/{runId}/cancel Cancel Run

Text, files, and images

Send plain content, or a contentBlock list that mixes text, files by URL or uploaded file ID, and images.

Context at two levels

Pass additional context and custom properties for a single message, or for the whole conversation.

Your own end users

Identify the requester with the x-boldagent-requesterid header, then list that user’s conversations.

Feedback on answers

Record whether an answer was helpful or not helpful, with an optional comment.

Human approval

Keep a person in the loop, even over the API

Set humanApprovalMode to require approval before an agent acts, or to approve automatically. When a conversation pauses for review, resume it with a decision in hitlResume.

approve
Let the pending action run as proposed.
edit
Change the action before it runs.
reject
Stop the action.
respond
Reply to the person instead.

API keys

One key, one user’s permissions

An API key represents the user who created it, and every request is authorized with that user’s access. Creating a key never grants extra permissions, so scope an integration by choosing whose key it uses.

  • Create keys from your BoldAgent profile
  • The token is shown once, at creation
  • Store it in a secrets manager, never in browser code, URLs, or logs
  • Rotate or revoke it right away if it may be exposed

Conventions

Predictable by Design

The same rules apply across every endpoint, so an integration that works for one resource works for the next.

Versioning

The current version is 1.0, and requests default to it. Set it in the URL path, the api-version query string, the X-Version header, or the media type, and use one method consistently.

Pagination and filtering

List operations can take Page, PerPage, and Filter, where supported. Check each endpoint for its defaults and limits.

Permissions and errors

Every operation lists the permission it needs. Expect standard status codes: 400 for validation, 401 for a missing or invalid key, 403 for missing access, and 404 for a wrong route or ID.

Resources

Start Building

Everything you need to make your first call.

API reference Every endpoint, with parameters, request and response schemas, required permissions, and curl examples. Authentication Create an API key, choose a header format, and keep your key secure. Knowledge base How-to articles for building, sharing, and deploying agents in BoldAgent.

Frequently Asked Questions

Agents and their versions, libraries with files, Q&A, and web sources, decision models, MCP servers, guardrail policies, categories, conversations, messages, runs, attachments, and sandbox environments.

Create an API key from your BoldAgent profile and send it with every request as X-API-Key: {yourapikey} or Authorization: ApiKey {yourapikey}. Use one format, over HTTPS.

https://{yourdomain}/developer-api/v1.0, where {yourdomain} is your BoldAgent organization's domain. Append the endpoint path documented for each operation.

Use Send Message for the complete answer in one response, Stream Message for server-sent events as the answer is written, or Submit Run to process it in the background and then stream it, check its status, or cancel it.

No. If you leave out the conversation ID, a new conversation is created automatically. You can also start one explicitly with Start Conversation.

Yes. Use contentBlock to combine text, files by URL or uploaded file ID, and images. Upload files for a conversation with Upload Attachment.

Yes. Set humanApprovalMode to required or auto_approve, and resume a paused conversation with hitlResume decisions: approve, edit, reject, or respond.

Exactly those of the user who created it. Each operation lists the permission it needs, and creating a key never grants additional access.

No. The token is shown once. Copy it and store it securely, and rotate or revoke it if it may have been exposed.

Make Your First API Call

Create an API key from your profile, send a message to an agent, and stream the answer back.

Quick start API reference