Submit Tasks via the API

The Pool Do API provides programmatic access for building integrations, automations, and custom clients.

Base URL

All API endpoints are served under /api/v1/ on your Pool Do server.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can generate API keys from your Profile page in the web UI.

Endpoints

Submit a Task

POST /api/v1/tasks

Request body:

{
  "pool_id": "uuid",
  "model": "llama3.2",
  "params": {
    "prompt": "Your prompt here",
    "temperature": 0.7,
    "max_tokens": 256
  }
}

Response:

{
  "id": "task-uuid",
  "status": "queued",
  "created_at": "2025-01-15T10:30:00Z"
}

Get Task Status

GET /api/v1/tasks/{id}

Returns the task with its current status and, if completed, the result.

List Tasks

GET /api/v1/tasks?pool_id=uuid&status=completed&limit=50

Submit a Batch

POST /api/v1/batches
Content-Type: multipart/form-data

Fields:

• pool_id — the pool to submit to
• file — a JSONL file of task definitions

Get Batch Status

GET /api/v1/batches/{id}

Rate Limits

API requests are rate-limited per API key. The current limits are returned in response headers:

• X-RateLimit-Limit — requests per minute
• X-RateLimit-Remaining — requests remaining in the current window

Error Responses

Errors return standard HTTP status codes with a JSON body:

{
  "error": "insufficient_credits",
  "message": "Not enough credits to submit this task. Current balance: 12.5"
}

| Code | Meaning | |------|---------| | 400 | Bad request — invalid parameters | | 401 | Unauthorized — missing or invalid API key | | 402 | Insufficient credits | | 404 | Resource not found | | 429 | Rate limit exceeded | | 500 | Internal server error |