Clavis API Reference

Base URL: https://clavisagent.com/v1/ — Bearer token authentication required on all protected endpoints.

Quick Start

Five steps from zero to a running agent with managed credentials:

1. Install the SDK: pip install clavis
2. Register: POST /v1/auth/register with email + password
3. Log in: POST /v1/auth/login → receive a JWT (24-hour expiry)
4. Register a service: POST /v1/services with a connector name (e.g. openai)
5. Store credentials: POST /v1/services/{service_id}/credentials with your API key or OAuth token

After that, call get_token() or proxy() from the SDK — Clavis handles token refresh and rate limiting automatically.

from clavis import ClavisClient

client = ClavisClient(api_key="eyJ...", base_url="https://clavisagent.com")

# Get a valid token — refreshed automatically if expired
token = await client.get_token("my-openai")
print(token.access_token)  # sk-...

# Or proxy a full request — auth injected, rate limits tracked
response = await client.proxy(
    "my-openai", "POST", "/v1/chat/completions",
    body={"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]},
)

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Tokens are obtained by logging in via POST /v1/auth/login and expire after 24 hours. There is no API key separate from the JWT — your login token is your API key.

Key Endpoints

Additional Endpoints

The following endpoints are also available. For full request/response schemas, use the Interactive Explorer below or fetch /openapi.json directly.

Supported Connectors

Pass one of these as connector_name when registering a service:

The api-key connector is a generic fallback for any service that accepts a static API key in an Authorization: Bearer header.

Error Codes

All error responses return JSON: {"detail": "human-readable message"}

Interactive API Explorer

Try live requests below. Click Authorize and paste your JWT to authenticate.