Usage

tip

To learn how to create and use business logic in your Worker, see the Functions and Services pages.

The Base Worker exposes several endpoints and features for task execution and monitoring.

Endpoints

Endpoint	Method	Description
/task	POST	Submit a task to the worker.
/health	GET	Get the status of the worker (public info, more details with authentication).
/logs	GET	Retrieve the last 1000 log lines (authentication required).
/on	POST	Enable the worker to accept new tasks.
/off	POST	Set the worker to maintenance mode (no new tasks accepted).

Slot Management

• Each worker manages a number of parallel slots (e.g., 10).
• If all slots are busy, new tasks are queued and prioritized (by priority field with 1 = highest priority, otherwise FIFO).
• Slot availability is updated in real time and can be pushed to the Load Balancer via WebSocket.

Task Handling

• Tasks specify group, function, contract, and optional priority.
• input represents the parameters accepted by the called function.
• The worker validates the request and executes the corresponding function.
• If the worker is saturated, tasks are queued and processed as slots become available.

Example contacting a Worker directly:

{
  "function": "hello",
  "input": { "name": "Andera" },
  "contract": 1,
  "priority": 1, // Optionnal
  "mode": "sync" // Can be sync, stream or webhook
}

Response Modes

The mode field in the /task payload controls how the Worker returns the result of your function. There are three supported modes:

1. sync (default)

• Behavior: The Worker executes the function and returns the result in the HTTP response.
• Usage:

  {
    "function": "hello",
    "input": { "name": "Andera" },
    "contract": 1,
    "priority": 1, // Optionnal
    "mode": "sync"
  }
• When to use: For most standard function calls where you want the result immediately.

2. stream

• Behavior: The Worker streams the result back to the client as it is produced (useful for long-running or incremental output).
• Prerequisite: The function must have supportsStreaming: true in its config.
• Usage:

  {
    "function": "hello",
    "input": { "name": "Andera" },
    "contract": 1,
    "priority": 1,
    "mode": "stream"
  }
• When to use: For functions that can produce output incrementally (e.g., chat, logs, progress updates).

3. webhook

• Behavior: The Worker executes the function and sends the result to a specified webhook URL instead of returning it in the HTTP response.
• Prerequisite: You must provide a webhook object with a mandatory url field in the payload. The headers field is optional.
• Usage:

  {
    "function": "hello",
    "input": { "name": "Andera" },
    "contract": 1,
    "priority": 1,
    "mode": "webhook",
    "webhook": {
      "url": "https://your-callback.url",
      "headers": {
        "Authorization": "Bearer my-token",
        "X-Custom-Header": "value"
      }
    }
  }
• Important: The webhook object must contain a url property when using mode: "webhook". The headers property is optional and only used to override or add to the default headers defined in the configuration (WEBHOOK_HEADERS).
• When to use: For asynchronous workflows or when you want the Worker to notify another service upon completion.

If mode is omitted, sync is used by default.

Maintenance Mode

Workers support a maintenance mode that allows you to temporarily stop accepting new tasks while letting current tasks finish. This is useful for safe updates, scaling, or graceful shutdowns.

• POST /off: Enable maintenance mode. The Worker will refuse new tasks, but ongoing tasks will continue until completion.
• POST /on: Disable maintenance mode. The Worker will accept new tasks again.

When to use:

• For direct usage, use maintenance mode before stopping or updating a Worker to avoid losing or interrupting tasks.
• When using the Load Balancer and before removing a Worker from the cluster (or from workers.json), set it to maintenance mode to ensure no new tasks are sent and current tasks finish cleanly.

Example:

curl -X POST http://localhost:3000/off -H 'Authorization: <AUTH_KEY>'
curl -X POST http://localhost:3000/on -H 'Authorization: <AUTH_KEY>'

Logs and Tags

• /logs endpoint provides the last 1000 log lines for monitoring and debugging. See the Logging page for details and best practices.
• Tags are dynamic metadata exposed by the worker (e.g., Chrome version, AI model used), accessible via /health with authentication or from the dashboard of the Load Balancer. See the Tags page for usage and examples.

OpenAPI & Swagger Documentation

The Base Worker automatically exposes interactive API documentation endpoints if the OPENAPI_ENABLED environment variable is set to true (default).

• Swagger UI:

  • Accessible at: /docs
  • Provides an interactive web interface to explore and test all available endpoints and their schemas.

• OpenAPI JSON:

  • Accessible at: /openapi
  • Returns the OpenAPI (Swagger) specification in JSON format, which can be used for client generation, integration, or further documentation.

These endpoints are useful for:

• Discovering all available API endpoints and their parameters
• Testing API calls directly from the browser
• Generating client SDKs or integrating with other tools that support OpenAPI

Note: For security, consider restricting access to these documentation endpoints in production environments (e.g., via authentication or IP allowlists).