Log In Get Started

API Documentation

Integrate Boost Agents AI capabilities into your applications with our powerful REST API.

API Reference

Getting Started

Endpoints

Webhooks

SDKs & Libraries

Home
Documentation
API Reference

API Overview

The Boost Agents API is organized around REST principles. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

The API is designed to make it easy to integrate Boost Agents AI capabilities into your applications, allowing you to automate tasks, process documents, and leverage our specialized AI agents programmatically.

Base URL

All API requests should be sent to:

https://api.boostagents.com/v1

API Versions

The current API version is v1. We recommend specifying a version in all API requests to ensure compatibility as the API evolves.

Content Types

All requests with a JSON body must include the Content-Type: application/json header. For file uploads, use Content-Type: multipart/form-data.

Request Structure

A typical API request includes:

  • The HTTP method (GET, POST, PUT, DELETE)
  • The endpoint URL
  • Headers (including authentication)
  • Request parameters (URL or body)
Example Request
curl -X POST https://api.boostagents.com/v1/tasks \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent": "marcom_maven", "description": "Create a social media post about our new product", "priority": "high", "due_date": "2025-04-15T14:00:00Z" }'

Note: Always keep your API keys secure and never expose them in client-side code or public repositories.

Authentication

Authentication to the Boost Agents API is performed using API keys. Each API key is associated with a specific user account and has configurable permissions.

API Keys

To obtain an API key:

  1. Log in to your Boost Agents account
  2. Navigate to Settings > API Keys
  3. Click "Create New API Key"
  4. Set a name and permissions for the key
  5. Click "Generate Key"

Important: API keys are displayed only once when created. Store your key securely; if you lose it, you'll need to generate a new one.

Authentication Methods

There are two ways to authenticate API requests:

1. Authorization Header (Recommended)

Include your API key in the request's Authorization header:

Authorization: Bearer YOUR_API_KEY

2. Query Parameter

Include your API key as a query parameter:

https://api.boostagents.com/v1/tasks?api_key=YOUR_API_KEY

We recommend using the Authorization header method for improved security.

Authentication Errors

If authentication fails, the API will return a 401 Unauthorized response:

{ "error": { "code": "unauthorized", "message": "Invalid API key or insufficient permissions" } }

Error Handling

The Boost Agents API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

  • 2xx range indicates success
  • 4xx range indicates an error that resulted from the provided information (e.g., missing required parameters, invalid API key)
  • 5xx range indicates an error with Boost Agents servers

Error Response Format

Error responses include a JSON object with an error object containing details about what went wrong:

{ "error": { "code": "invalid_request", "message": "The request was unacceptable, often due to missing a required parameter", "param": "description", // Optional: The parameter that caused the error "details": [] // Optional: Additional error details } }

Common Error Codes

HTTP Status Error Code Description
400 invalid_request The request was malformed or missing required parameters
401 unauthorized Authentication failed or insufficient permissions
403 forbidden The API key doesn't have permission to perform the request
404 not_found The requested resource doesn't exist
409 conflict The request conflicts with the current state of the resource
429 rate_limit_exceeded Too many requests hit the API too quickly
500 internal_error An error occurred on the server

Handling Errors

We recommend implementing error handling that:

  • Checks for HTTP status codes in the 4xx and 5xx ranges
  • Parses the error object to extract relevant details
  • Implements retry logic with exponential backoff for 429 and 5xx errors
  • Logs errors for debugging purposes

Tasks API

The Tasks API allows you to create, manage, and monitor AI agent tasks programmatically. Use these endpoints to automate workflows and integrate AI task execution into your applications.

POST /tasks

Create a new task and assign it to an AI agent.

Request Parameters

Parameter Type Description
agent Required string The ID of the agent to assign the task to (e.g., "marcom_maven", "finance_navigator")
description Required string A detailed description of the task to be performed
priority Optional string Task priority: "low", "medium", or "high". Default is "medium"
due_date Optional string (ISO 8601) The due date and time for the task
attachments Optional array Array of document IDs to attach to the task
execute_immediately Optional boolean Whether to execute the task immediately after creation. Default is false
Example Request
curl -X POST https://api.boostagents.com/v1/tasks \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "agent": "marcom_maven", "description": "Create a social media post about our new product launch", "priority": "high", "due_date": "2025-04-15T14:00:00Z", "attachments": ["doc_123abc"], "execute_immediately": true }'

Responses

201 Task created successfully
{ "id": "task_abc123", "agent": "marcom_maven", "description": "Create a social media post about our new product launch", "priority": "high", "due_date": "2025-04-15T14:00:00Z", "status": "pending", "created_at": "2025-04-10T12:34:56Z", "attachments": ["doc_123abc"], "execute_immediately": true }
400 Invalid request parameters
{ "error": { "code": "invalid_request", "message": "The request was unacceptable", "param": "agent", "details": ["Invalid agent ID provided"] } }
GET /tasks/{task_id}

Retrieve the details of a specific task.

Path Parameters

Parameter Type Description
task_id Required string The unique identifier of the task
Example Request
curl -X GET https://api.boostagents.com/v1/tasks/task_abc123 \ -H "Authorization: Bearer YOUR_API_KEY"

Responses

200 Task retrieved successfully
{ "id": "task_abc123", "agent": "marcom_maven", "description": "Create a social media post about our new product launch", "priority": "high", "due_date": "2025-04-15T14:00:00Z", "status": "completed", "created_at": "2025-04-10T12:34:56Z", "completed_at": "2025-04-10T12:45:23Z", "result": "Here's a draft social media post: 'Exciting news! Our new product is now available...'", "attachments": ["doc_123abc"] }
404 Task not found
{ "error": { "code": "not_found", "message": "The requested task could not be found" } }
GET /tasks

List all tasks, with options for filtering and pagination.

Query Parameters

Parameter Type Description
status Optional string Filter by task status: "pending", "in_progress", "completed", or "failed"
agent Optional string Filter by agent ID
limit Optional integer Maximum number of tasks to return (default: 20, max: 100)
offset Optional integer Number of tasks to skip (for pagination)
Example Request
curl -X GET "https://api.boostagents.com/v1/tasks?status=completed&agent=marcom_maven&limit=5" \ -H "Authorization: Bearer YOUR_API_KEY"

Responses

200 Tasks retrieved successfully
{ "data": [ { "id": "task_abc123", "agent": "marcom_maven", "description": "Create a social media post", "status": "completed", "created_at": "2025-04-10T12:34:56Z" }, { "id": "task_def456", "agent": "marcom_maven", "description": "Write a product description", "status": "completed", "created_at": "2025-04-09T15:12:34Z" } // Additional tasks... ], "pagination": { "total": 42, "limit": 5, "offset": 0, "has_more": true } }

Ready to Integrate?

Get started with the Boost Agents API to automate your business workflows and integrate AI capabilities into your applications.