Run your first Qoder Cloud Agent in five steps.
Get your first Qoder Cloud Agent running in five steps: configure a PAT or SA Key, pick an environment, create an Agent, create a Session, and exchange messages. The whole flow uses only
Personal users use a PAT. Service Accounts can call the API directly with an SA Key. The remaining steps use the common
List the available environments and capture the ID:
Example response:
Define a general-purpose Agent with a shell tool:
Example response:
Creating a Session requires two parameters:
Example response:
Send a user message to the Session, then receive Agent responses live over SSE:
Example event stream output:
The whole flow combined into a single runnable script:
Q: I'm getting 401 Unauthorized.
A: Check that
curl — no SDK required.
Prerequisites
- A Qoder account
- A terminal (macOS, Linux, or WSL)
curl, plusjq(optional, for formatting JSON)
Windows users
Windows users
The commands in this guide use bash syntax. Windows users should use one of the following:
- Git Bash (recommended): included with Git for Windows
- WSL: install via
wsl --install
- Set environment variables:
$env:QODER_ACCESS_TOKEN="your-token"(notexport) - Use real curl: type
curl.exe(PowerShell aliasescurltoInvoke-WebRequest) - Install jq separately:
winget install jqlang.jq
Step 1: Configure access credentials
Personal users use a PAT. Service Accounts can call the API directly with an SA Key. The remaining steps use the common QODER_ACCESS_TOKEN environment variable; existing integrations can continue to use an SAT.
Choose API endpoints in the same region as your account, credentials, and resources:
Option 1: PAT (personal user)
- Sign in to the Qoder console.
- Open Settings → Personal Access Tokens.
- Click Create Token, then set a name and expiration.
- Copy the token and set it as an environment variable:
The PAT is shown only once at creation. Save it securely right away.
Option 2: SA Key (Service Account API Key)
- Sign in to the Qoder console as an organization administrator.
- Create or select a Service Account under organization management.
- Create an API Key from the Service Account details page and make sure the Service Account is bound to the target workspace. See Personal and enterprise spaces.
- Copy the full SA Key and set the environment variables:
This guide uses Managed APIs (
/api/v1/cloud/*), which accept the SA Key directly as a Bearer credential without SAT exchange or renewal. The full SA Key is shown only once at creation; store it securely. If you need a short-lived token, follow Authentication to obtain an SAT and set QODER_ACCESS_TOKEN to that SAT.Step 2: Pick an Environment
List the available environments and capture the ID:
Step 3: Create an Agent
Define a general-purpose Agent with a shell tool:
Step 4: Create a Session
Creating a Session requires two parameters: agent (Agent ID or object) and environment_id (Environment ID).
Bind the Agent to the Environment to create a runtime instance:
The Session starts in
idle status. It will only begin processing once you send a message in the next step.Step 5: Send a Message and Stream Events
Send a user message to the Session, then receive Agent responses live over SSE:
- Every event (except
heartbeat) includes anid:line and the JSON payload containsid,type, andprocessed_atfields. heartbeatevents are sent approximately every 15 seconds to keep the connection alive.- The
contentfield inagent.messageuses the[{"type":"text","text":"..."}]array format. session.status_running/session.status_idlecarry no extra fields beyondid,type,processed_at, and (for idle)stop_reason.agent.thinkingsignals that the model is reasoning but contains nocontentortextfield.
End-to-End Script
The whole flow combined into a single runnable script:
FAQ
Q: I'm getting 401 Unauthorized.
A: Check that $QODER_ACCESS_TOKEN contains the full credential and the API endpoint matches its region. Replace an invalid PAT. For direct SA Key calls, check that the key is valid and has not been revoked. If you use an SAT, exchange the SA Key for a new SAT after it expires.
Q: Creating an Agent returns 400 Bad Request.
A: Verify the request JSON. The model field must be a valid value (such as "ultimate"), and tools must be an array.
Q: The Session stays in idle and emits no events.
A: A newly created Session starts in idle status. You must send a user.message event (Step 5) to trigger Agent execution.
Q: My SSE stream disconnected.
A: The stream endpoint supports the Last-Event-ID header for reconnection replay. Pass the last event id you received; the stream resumes from the event after that ID. To query historical events, use GET /api/v1/cloud/sessions/{id}/events?order=desc.
Q: GET /api/v1/cloud/environments returns an empty array.
A: New accounts may not have a pre-provisioned environment. Follow the tip in Step 2 to create one manually.