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 dispatch an execution.
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 → Developer → API keys, create a key, and copy it. It's shown only once. A key works across your organization; you pick the project it acts in at step 4. Full details: Authentication & API keys.
2. Install the tools
Download the Compass wheel from Settings → Developer → SDK & CLI, then install the command-line tool:
uv tool install "./compass_core-<version>-py3-none-any.whl[cli]"The same wheel is also the Python SDK — see API, CLI & SDK for both in depth.
3. Authenticate
compass auth login --url https://your-compass-urlYou'll be prompted for the API key from step 1. The CLI exchanges it for a short-lived access token on every call, so the key is the only thing you handle. Confirm it works:
compass auth whoami4. Pick a project
Keys are organization-scoped, so choose which project to work in:
compass projects list
compass projects use <project-id>5. Run something
List your work, then dispatch an execution and follow it live:
compass workflows list
compass execute --deployment <deployment-id> --input topic="Q3 report" --followPrefer Python? The same thing with the SDK:
import asyncio
from compass_core import Compass
async def main():
async with Compass(
credential="<your-api-key>",
base_url="https://your-compass-url",
project_id="<project-id>",
) as client:
execution = await client.executions.create(
deployment_id="<deployment-id>",
input={"topic": "Q3 report"},
)
print(execution.id, execution.status)
asyncio.run(main())