API quickstart

Get a key, install the tools, and run a deployment from your terminal or your code.

This is the fastest path to calling Compass from outside the app. You'll create an API key, install the command-line tool, and trigger a run.

You'll need

A deployed agent or workflow to run, and your Compass URL — the same address you use to sign in.

1. Create an API key

In the app, go to Settings → Developers → API Keys, create a key scoped to your project, and copy the secret. It's shown only once. Full details: Authentication & API keys.

2. Install the tools

Download the Compass wheel from Settings → Developers → SDK / CLI, then install the command-line tool:

uv tool install "./compass_cli.whl[cli]"

The same wheel is also the Python SDK — see The Compass CLI and The Compass SDK for both.

3. Authenticate

compass auth login --url https://your-compass-url

You'll be prompted for the API key from step 1. Confirm it works:

compass auth whoami

4. Run something

List your work, then start a run and follow it live:

compass workflows list
compass run --deployment <deployment-id> --input topic="Q3 report" --follow

Prefer Python? The same thing with the SDK:

import asyncio
from compass_core import Compass

async def main():
    async with Compass(token="<your-api-key>", base_url="https://your-compass-url") as client:
        run = await client.runs.create(
            deployment_id="<deployment-id>",
            input={"topic": "Q3 report"},
        )
        print(run.id, run.status)

asyncio.run(main())