Your First API Request

Generate a key, make a chat request, and see it in your usage — in a few minutes. Copy-paste examples in cURL, JavaScript, Python, and Node.

4 min read

Prerequisites

  • A workspace and project (a default project is created with your workspace — see Quick Start).
  • A secret API key. Generate one on the API keys page.
  1. 1

    Generate an API key & copy the secret

    On the API keys page, click Create secret key. Copy the secret (carrier_sk_…) — it is shown only once.
  2. 2

    Verify the key (optional)

    Confirm the key resolves to the right workspace and project:
bash
curl https://api.carrieros.ai/v1/auth/verify \
  -H "Authorization: Bearer carrier_sk_live_YOUR_KEY"

Call the Chat API

Send a POST to /v1/chat with a mode and a message:

bash
curl -X POST https://api.carrieros.ai/v1/chat \
  -H "Authorization: Bearer carrier_sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "general",
    "message": "Explain OAuth in two sentences."
  }'

Receive the response

You get the answer plus a session_id you can reuse to continue the conversation, and tokens_used:

json
{
  "success": true,
  "data": {
    "id": "…",
    "response": "OAuth is an open standard for delegated access…",
    "session_id": "25f37117-…",
    "tokens_used": 523
  }
}

Use the same key in the CLI

The CLI authenticates with the exact same secret key:

bash
npm install -g @carrieros/cli
cos login        # paste carrier_sk_…
cos              # chat in the interactive shell

Monitor usage

Every request is metered. Check it from the API or the dashboard:

bash
curl https://api.carrieros.ai/v1/usage \
  -H "Authorization: Bearer carrier_sk_live_YOUR_KEY"
Requests show up in Usage and Logs in the dashboard, and in cos usage.

Related pages

Chat API

Full request/response reference

Authentication

Bearer keys & key types

CLI Quick Start

Chat from your terminal

Usage API

Requests, tokens, and cost