zeriq-team

The official Python SDK for the Zeriq Teams API: your AI teammates' knowledge, answers, rooms, action items and meetings, from your own systems.

• Python 3.9+, sync and async clients, built on httpx.
• Results are plain dicts, typed with TypedDicts generated from the API's OpenAPI spec (zeriq_team.types).
• Retries 429, 5xx and network errors with backoff, and honours Retry-After. Every POST gets an Idempotency-Key, so retries never create anything twice.

pip install zeriq-team

Quick start

from zeriq_team import Zeriq

zq = Zeriq()  # reads ZERIQ_TEAM_API_KEY (and ZERIQ_TEAM_BASE_URL)

# Knowledge: upsert by your own id, then search (no AI model, no credits)
zq.knowledge.documents.upsert(external_id="wiki:refunds", title="Refunds", text="…")
hits = zq.knowledge.search(query="refund policy", top_k=5)["data"]

# Ask an AI teammate (no tools unless you allow them)
answer = zq.personas.ask("prs_…", input="Draft a reply to this customer: …")
print(answer["answer"], answer["usage"])

# Rooms: create, post, stream the replies as they arrive, end
room = zq.rooms.create(title="Pricing review", personas=["prs_…"])
sent = zq.rooms.messages.send(room["id"], content="Should we add annual plans?")
for event in zq.rooms.stream(room["id"], run_id=sent["run_id"]):  # ends with the run
    if event["event"] == "message.created":
        print(event["data"]["message"]["content"])
zq.rooms.end(room["id"])

# Lists return the first page; iterate to walk every page
for item in zq.action_items.list(status="open"):
    zq.action_items.update(item["id"], external_ref="https://linear.app/…")

Async is the same API, awaited:

from zeriq_team import AsyncZeriq

async with AsyncZeriq() as zq:
    answer = await zq.personas.ask("prs_…", input="…")
    async for item in zq.action_items.list(status="open"):
        ...

For QA, set base_url="https://api.qa.zeriq.app".

Webhooks

endpoint = zq.webhooks.endpoints.create(url="https://example.com/zeriq", event_types=["action_item.created"])
secret = endpoint["secret"]  # shown only now

# In your handler, with the raw request body:
from zeriq_team import webhooks, WebhookVerificationError

event = webhooks.verify(raw_body, headers["Zeriq-Signature"], secret)
if event["type"] == "action_item.created":
    ...

Errors

Every API error is an APIError with status, code, param and request_id. Subclasses: InvalidRequestError (400), AuthenticationError (401), CreditsExhaustedError (402 — retry with allow_downgrade=True), PlanLimitError (402), InsufficientScopeError (403, param is the missing scope), ToolNotPermittedError (403), NotFoundError (404, also for other workspaces' objects), RateLimitError (429 after retries), plus APIConnectionError / APITimeoutError. Results carry the ID too: answer.request_id.

Options

Zeriq(api_key=..., base_url=..., timeout=60.0, max_retries=2, http_client=httpx.Client(...))
zq.rooms.create(title="x", idempotency_key="my-key")

Examples

examples/: a knowledge-base sync, an async room bot, and action items → Linear.

ZERIQ_TEAM_API_KEY=zqt_sk_… python examples/kb_sync.py

Development

python -m venv .venv && .venv/bin/pip install -e '.[dev]'
scripts/generate.sh      # types from ../team-api-spec/openapi.json
.venv/bin/python -m pytest

The contract tests that run this SDK against the real API app live in services/team-agent/tests/test_sdk_contract.py.