Install and authenticate

Install

The package is ellipsis-dev on PyPI; the import name is ellipsis.

pip install ellipsis-dev

Live streaming needs one extra dependency:

pip install 'ellipsis-dev[stream]'

Python 3.10 or newer. The client depends on httpx and pydantic v2; the stream extra adds websockets.

Authenticate

Create an API key under Platform → API keys in the dashboard. The secret starts with ellipsis_key_ and is shown only once. Keep it in an environment variable rather than in source:

export ELLIPSIS_API_TOKEN="ellipsis_key_..."

api_key is the client's only required argument:

import os

from ellipsis import Ellipsis

client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])

An API key authenticates as your organization. A CLI user token, which agent login mints, authenticates as you personally and works in exactly the same argument. Either is rejected with 401 if invalid or revoked.

Client options

client = Ellipsis(
    api_key=os.environ["ELLIPSIS_API_TOKEN"],
    base_url="https://api.ellipsis.dev",
    timeout=60.0,
    max_retries=3,
)

base_url points the client at a non-default host. timeout is per request, in seconds. max_retries bounds automatic retries, which apply to transport failures and to 429, 502, 503, and 504, with exponential backoff and jitter. A 429 response honors its Retry-After header. Other statuses are never retried: a 404 or 422 would fail identically the second time.

Closing the client

The synchronous client holds a connection pool. Close it when you are done, or use it as a context manager:

with Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"]) as client:
    print(client.me().customer_login)

The async client is the same, with async with and await client.close().