Skip to main content
The NimbleBrain API provides programmatic access to all Studio features. Use it to manage agents, execute playbooks, and build custom integrations.

​
Base URL

https://studio-api.nimblebrain.ai/v1

​
Authentication

All API requests require authentication using a Bearer token. Get your API key from Settings > API Keys in NimbleBrain Studio. 
curl -H "Authorization: Bearer nb_live_xxxxx" \
  https://studio-api.nimblebrain.ai/v1/agents

​
API Key Formats

PrefixEnvironment
nb_live_Production
nb_test_Testing/Development

​
Interactive Documentation

For the full interactive API reference with request/response examples, visit:

Swagger Documentation

Interactive API explorer with try-it-out functionality

​
Available Endpoints

​
Agents

MethodEndpointDescription
GET/v1/agentsList all agents
GET/v1/agents/:idGet agent details

​
Conversations

MethodEndpointDescription
POST/v1/agents/:agentId/conversationsCreate conversation
GET/v1/agents/:agentId/conversations/:idGet conversation

​
Messages

MethodEndpointDescription
GET/v1/agents/:agentId/conversations/:convId/messagesList messages
POST/v1/agents/:agentId/conversations/:convId/messagesSend message
Add stream: true to the message body and set Accept: text/event-stream header to receive streaming responses via SSE.

​
Playbooks

MethodEndpointDescription
GET/v1/playbooksList all playbooks
GET/v1/playbooks/:idGet playbook details
POST/v1/playbooks/:id/executeExecute a playbook

​
Executions

MethodEndpointDescription
GET/v1/executions/:idGet execution status

​
Response Format

All responses are JSON with consistent structure: Success: 
{
  "agents": [...],
  "meta": {
    "total": 5,
    "page": 1
  }
}
Error: 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Agent not found"
  }
}

​
HTTP Status Codes

CodeDescription
200Success
201Created
400Bad request (invalid parameters)
401Unauthorized (invalid/missing API key)
403Forbidden (insufficient permissions)
404Not found
429Rate limited
500Internal server error

​
Rate Limits

API requests are rate limited per workspace:
PlanRequests per minute
Free60
Pro300
EnterpriseCustom
Rate limit headers are included in responses:
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Requests remaining
  • X-RateLimit-Reset: Unix timestamp when limit resets

​
SDK vs Direct API

For most use cases, we recommend using the TypeScript SDK instead of calling the API directly. The SDK provides:
  • Type-safe methods
  • Automatic error handling
  • Streaming support built-in
  • Simpler authentication
Use the API directly when:
  • Building in a language without an SDK
  • Need low-level control
  • Integrating with existing HTTP clients

​
Example: Execute a Playbook

# Execute a playbook
curl -X POST \
  -H "Authorization: Bearer nb_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"parameters": {"ticker": "AAPL"}}' \
  https://studio-api.nimblebrain.ai/v1/playbooks/pb_123/execute

# Response
{
  "id": "exec_456",
  "status": "queued"
}

# Poll for completion
curl -H "Authorization: Bearer nb_live_xxxxx" \
  https://studio-api.nimblebrain.ai/v1/executions/exec_456

# Response when complete
{
  "id": "exec_456",
  "status": "completed",
  "result": "Analysis: AAPL shows strong momentum...",
  "durationMs": 4523
}

TypeScript SDK

Type-safe SDK for Node.js and browsers

API Keys

Manage your API keys in Studio