Fivexer Python SDK

The Python SDK (fivexer) supports Python 3.9+, ships sync and async clients for all three credential planes, and is type-annotated end to end (py.typed).

Install

bash
pip install fivexer

Quickstart

python
from fivexer import Fivexer, CreateTask, UpsertWorker, ListDecisionsQuery

client = Fivexer(base_url="https://api.fivexer.com", api_key="sk_test_...")

client.workers.upsert(UpsertWorker(id="agent_1", tags=["english", "billing"]))
task = client.tasks.create(CreateTask(tags=["english", "billing"], priority=90))
print(task.id, task.status)

decisions = client.decisions.list(ListDecisionsQuery(task_id=task.id))

Hand work off and wait for the result

Give the task your own id so a retry cannot create a second one, say what a finished result must look like, and wait for it. outcome returns as soon as the task is done or the wait (up to 25 seconds) runs out; the SDK raises its own read timeout to cover the wait.

python
from fivexer import CreateTask, ResultContract

client.tasks.create(CreateTask(
    id="audit-2026-10-10",
    tags=["seo"],
    title="Audit the pricing page",
    result_contract=ResultContract(
        schema={"type": "object", "required": ["url"], "properties": {"url": {"type": "string"}}},
        acceptance_criteria="A link to the published report.",
    ),
))

outcome = client.tasks.outcome("audit-2026-10-10", wait_ms=25_000)
while not outcome.done:
    outcome = client.tasks.outcome("audit-2026-10-10", wait_ms=25_000)
print(outcome.status, outcome.worker_id, outcome.result)

A result that misses the schema is refused with result_invalid and stays with the worker to fix; a worker who cannot do the job completes with success: false, which always goes through. See the MCP agent toolset for the same flow over MCP.

Async

python
from fivexer import AsyncFivexer

client = AsyncFivexer(base_url="https://api.fivexer.com", api_key="sk_test_...")
worker_id = await client.workers.upsert(UpsertWorker(id="agent_1", tags=["english"]))

Errors and quotas

python
from fivexer import FivexerApiError

try:
    client.tasks.create(CreateTask(tags=["english"]))
except FivexerApiError as e:
    print(e.status_code, e.code)
    print(e.retry_after)
    print(client.quota.task_rate_remaining)

Worker portal

python
from fivexer import FivexerWorker, WorkerLogin

worker = FivexerWorker(base_url="https://api.fivexer.com")
worker.login(WorkerLogin(workspace_id="ws_1", worker_id="agent_1", pin="4821"))
worker.accept(worker.queue().task_ids[0])

Supervisor

python
from fivexer import FivexerSupervisor, AcceptSupervisorInvite

sv = FivexerSupervisor(base_url="https://api.fivexer.com")
sv.accept_invite(AcceptSupervisorInvite(token=token_from_link))

board = sv.overview()
sv.assign(board.parked[0].id, board.crew[0].worker_id)

Supervisor actions are flat methods (unpark, set_priority, assign, set_availability). See the supervisor plane.

Every session client has an async twin — AsyncFivexer, AsyncFivexerWorker, and AsyncFivexerSupervisor — with the same method names. The sync clients are context managers, so with FivexerWorker(...) as worker: closes the underlying connection pool for you.

Webhooks

python
from fivexer import Webhook

event = Webhook.construct_event(
    payload=raw_body_bytes,
    header=request.headers["x-fivexer-signature"],
    secret="whsec_...",
)