API Overview

Complete reference for the Browserman REST API.

Base URL

https://api.browserman.run

All API requests should be made to this base URL.

Authentication

Authenticate using API keys in the Authorization header:

bash

Authorization: Bearer YOUR_API_KEY

Example:

bash

curl https://api.browserman.run/api/platforms \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx"

Getting API Keys

Visit app.browserman.run
Navigate to Settings > API Keys
Click Generate New Key
Store the key securely (shown only once)

Request Format

Headers

All POST/PUT requests should include:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Body

Request bodies should be valid JSON:

json

{
  "platform": "twitter",
  "tool": "createTweet",
  "accountName": "my-account",
  "parameters": {
    "text": "Hello World!"
  }
}

Response Format

Success Response

json

{
  "success": true,
  "data": {
    "taskId": "task_abc123",
    "state": "pending",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Error Response

json

{
  "success": false,
  "error": {
    "code": "ACCOUNT_NOT_FOUND",
    "message": "Account 'my-account' not found for platform 'twitter'",
    "details": {}
  }
}

Core Endpoints

Platforms

Get information about supported platforms and their tools.

bash

# List all platforms
GET /api/platforms

# Get platform schema
GET /api/platforms/schema

# Get specific platform details
GET /api/platforms/:platformId

Learn more →

Accounts

Manage your connected social media accounts.

bash

# List all accounts
GET /api/accounts

# Get account details
GET /api/accounts/:accountId

# Filter by platform
GET /api/accounts?platform=twitter

# Create account (OAuth)
POST /api/accounts/oauth/authorize

# Delete account
DELETE /api/accounts/:accountId

Learn more →

Tasks

Create and manage automation tasks.

bash

# Create a task
POST /api/tasks

# Get task status
GET /api/tasks/:taskId

# List tasks
GET /api/tasks

# Cancel task
DELETE /api/tasks/:taskId

Learn more →

Rate Limits

API rate limits (per API key):

Free tier: 100 requests/hour, 1,000 requests/day
Pro tier: 1,000 requests/hour, 10,000 requests/day
Enterprise: Custom limits

Rate limit headers in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

Error Codes

Common error codes you might encounter:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Too many requests
`ACCOUNT_NOT_FOUND`	400	Account doesn't exist
`INVALID_PARAMETERS`	400	Invalid request parameters
`PLATFORM_ERROR`	502	Platform-specific error
`TIMEOUT`	504	Task execution timeout
`INTERNAL_ERROR`	500	Server error

Common Patterns

Creating a Task

Request:

bash

curl -X POST https://api.browserman.run/api/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "twitter",
    "tool": "createTweet",
    "accountName": "my-account",
    "parameters": {
      "text": "Hello from Browserman!"
    }
  }'

Response:

json

{
  "success": true,
  "data": {
    "taskId": "task_abc123",
    "state": "pending",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

Checking Task Status

Request:

bash

curl https://api.browserman.run/api/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "success": true,
  "data": {
    "taskId": "task_abc123",
    "state": "completed",
    "result": {
      "success": true,
      "output": "Tweet posted successfully"
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "completedAt": "2024-01-15T10:30:15Z"
  }
}

Listing Accounts

Request:

bash

curl https://api.browserman.run/api/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json

{
  "success": true,
  "data": {
    "accounts": [
      {
        "id": "acc_123",
        "name": "my-twitter",
        "platform": "twitter",
        "status": "active",
        "createdAt": "2024-01-10T08:00:00Z"
      },
      {
        "id": "acc_124",
        "name": "my-xueqiu",
        "platform": "xueqiu",
        "status": "active",
        "createdAt": "2024-01-11T09:00:00Z"
      }
    ],
    "total": 2
  }
}

Pagination

List endpoints support pagination:

bash

GET /api/tasks?page=1&limit=20

Parameters:

page - Page number (default: 1)
limit - Items per page (default: 20, max: 100)

Response:

json

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Filtering

Many list endpoints support filtering:

bash

# Filter accounts by platform
GET /api/accounts?platform=twitter

# Filter tasks by state
GET /api/tasks?state=completed

# Filter tasks by date
GET /api/tasks?from=2024-01-01&to=2024-01-31

Sorting

Control sorting with query parameters:

bash

# Sort by creation date (newest first)
GET /api/tasks?sort=-createdAt

# Sort by name (alphabetical)
GET /api/accounts?sort=name

Prefix with - for descending order.

Webhooks

Configure webhooks to receive task completion notifications:

bash

POST /api/webhooks

Request:

json

{
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "task.failed"],
  "secret": "your-webhook-secret"
}

Webhook Payload:

json

{
  "event": "task.completed",
  "taskId": "task_abc123",
  "timestamp": "2024-01-15T10:30:15Z",
  "data": {
    "state": "completed",
    "result": {...}
  }
}

OpenAPI Schema

Get the complete OpenAPI schema:

bash

curl https://api.browserman.run/api/platforms/schema

Use this to:

Generate API clients
Validate requests
Explore available tools
Build integrations

SDK and Client Libraries

JavaScript/TypeScript

javascript

import { BrowsermanClient } from '@browserman/client';

const client = new BrowsermanClient({
  apiKey: 'YOUR_API_KEY'
});

// Post a tweet
const task = await client.twitter.createTweet({
  accountName: 'my-account',
  text: 'Hello World!'
});

// Check status
const status = await client.tasks.get(task.taskId);

Python

python

from browserman import BrowsermanClient

client = BrowsermanClient(api_key='YOUR_API_KEY')

# Post a tweet
task = client.twitter.create_tweet(
    account_name='my-account',
    text='Hello World!'
)

# Check status
status = client.tasks.get(task.task_id)

cURL Examples

See platform-specific API references for cURL examples.

Best Practices

1. Handle Rate Limits

Check rate limit headers and back off when needed:

javascript

if (response.headers['x-ratelimit-remaining'] < 10) {
  await sleep(60000); // Wait 1 minute
}

2. Retry Failed Requests

Implement exponential backoff:

javascript

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

3. Poll Task Status

Check task status periodically:

javascript

async function waitForTask(taskId, timeout = 300000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const status = await getTaskStatus(taskId);

    if (status.state === 'completed') {
      return status.result;
    } else if (status.state === 'failed') {
      throw new Error(status.error);
    }

    await sleep(5000); // Check every 5 seconds
  }

  throw new Error('Task timeout');
}

4. Validate Parameters

Use the OpenAPI schema to validate requests before sending:

javascript

import Ajv from 'ajv';

const ajv = new Ajv();
const schema = await fetchSchema();
const validate = ajv.compile(schema);

if (!validate(requestData)) {
  console.error(validate.errors);
}

5. Secure API Keys

Use environment variables
Never commit to version control
Rotate regularly
Create separate keys for different environments

API Versioning

The API is currently at version 1. Future versions will be indicated in the URL:

https://api.browserman.run/v2/...

Current version (v1) is the default and doesn't require version in URL.

Support

Documentation: Browse these guides
API Status: Check dashboard for status updates
Support: Contact via dashboard
Community: Access community forum through dashboard

API Overview ​

Base URL ​

Authentication ​

Getting API Keys ​

Request Format ​

Headers ​

Body ​

Response Format ​

Success Response ​

Error Response ​

Core Endpoints ​

Platforms ​

Accounts ​

Tasks ​

Rate Limits ​

Error Codes ​

Common Patterns ​

Creating a Task ​

Checking Task Status ​

Listing Accounts ​

Pagination ​

Filtering ​

Sorting ​

Webhooks ​

OpenAPI Schema ​

SDK and Client Libraries ​

JavaScript/TypeScript ​

Python ​

cURL Examples ​

Best Practices ​

1. Handle Rate Limits ​

2. Retry Failed Requests ​

3. Poll Task Status ​

4. Validate Parameters ​

5. Secure API Keys ​

API Versioning ​

Support ​

Next Steps ​

API Overview

Base URL

Authentication

Getting API Keys

Request Format

Headers

Body

Response Format

Success Response

Error Response

Core Endpoints

Platforms

Accounts

Tasks

Rate Limits

Error Codes

Common Patterns

Creating a Task

Checking Task Status

Listing Accounts

Pagination

Filtering

Sorting

Webhooks

OpenAPI Schema

SDK and Client Libraries

JavaScript/TypeScript

Python

cURL Examples

Best Practices

1. Handle Rate Limits

2. Retry Failed Requests

3. Poll Task Status

4. Validate Parameters

5. Secure API Keys

API Versioning

Support

Next Steps