Quickstart - Qoder CN

Get your first Qoder Cloud Agent running in five steps: obtain a PAT or SAT, select an environment, create an agent, create a session, and exchange messages. All you need is curl—no SDK installation is required.

Prerequisites

A Qoder account
A terminal environment (macOS, Linux, or WSL)
curl and jq

For Windows users: The commands in this document use bash syntax. We recommend using Git Bash (included with Git for Windows) or WSL (install with wsl --install). If you use PowerShell, you must adapt the commands: set an environment variable with $env:QODER_ACCESS_TOKEN="your-token", use curl.exe to bypass PowerShell's curl alias, and install jq separately (e.g., winget install jqlang.jq).

Step 1: Obtain an access token

Choose a PAT or SAT based on the calling identity. The remaining steps use the common QODER_ACCESS_TOKEN environment variable. Set the service endpoints first. The SAT exchange and business API requests must use endpoints in the same region:

export QODER_OPENAPI_BASE_URL="https://openapi.qoder.com.cn"
export QODER_API_BASE_URL="https://api.qoder.com.cn"

Option 1: PAT (personal user)

Sign in to the Qoder Console.
Navigate to Settings > Personal Access Tokens.
Click Create Token, then set a name and expiration.
Copy the token and set it as an environment variable:

export QODER_PAT="your-personal-access-token"
export QODER_ACCESS_TOKEN="$QODER_PAT"

The PAT is shown only once at creation. Save it securely right away.

Option 2: SAT (Service Account Token)

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. You do not select scopes when creating the key; specify the required scopes when exchanging it for an SAT.
Copy the SA Key, then exchange it for an SAT:

export QODER_SA_KEY="sa-key"

SAT_RESPONSE=$(curl --silent --show-error --location "$QODER_OPENAPI_BASE_URL/api/v1/serviceToken/exchange" \
  --header "Authorization: Bearer $QODER_SA_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "audience": "qoder",
    "scope": "qca.access",
    "ttl_seconds": 43200
  }')

export QODER_SAT="$(printf '%s' "$SAT_RESPONSE" | jq -r '.access_token')"
export QODER_ACCESS_TOKEN="$QODER_SAT"

Use the SA Key only to exchange for an SAT; do not send it directly to Cloud Agents APIs. An SAT is valid for at most 12 hours. Exchange the SA Key again after the SAT expires.

If the same server-side integration also calls Forward APIs, use "scope": "qca.access forward.access" in the exchange request. This SAT has administrator access to Forward resources under the account associated with the Service Account and must be used only in a trusted server-side environment. See Authentication.

Step 2: Select an environment

List your available environments to get an environment ID:

curl -s "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" | jq .

If the response returns "data": [] (an empty array), your account has no environments yet. Create one as follows:

curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/environments" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "default"}' | jq .

Step 3: Create an agent

Define a general-purpose agent with shell tools:

curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "instructions": "You are a helpful coding assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }' | jq .

Note the id field in the response (e.g., agent_019e...). You will need it to create a session in the next step.

Step 4: Create a session

Creating a session requires two parameters: agent (the agent ID or object) and environment_id (the environment ID). Bind the agent to an environment to create a running instance:

curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_YOUR_AGENT_ID",
    "environment_id": "env_YOUR_ENV_ID"
  }' | jq .

After creation, the session enters an idle state. The agent begins executing only after you send it a message in the next step.

Step 5: Send a message and receive events

Send a user message to the session, then receive the agent's responses in real-time from an SSE stream:

# Send a message
curl -s -X POST "$QODER_API_BASE_URL/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": [{"type": "text", "text": "Write a Python function that calculates fibonacci numbers"}]
  }'

# Receive the SSE event stream
curl -sN "$QODER_API_BASE_URL/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

The API sends a heartbeat event approximately every 15 seconds to keep the connection alive. The content field of an agent.message event uses an array format: [{"type":"text","text":"..."}].

FAQ

Q: What should I do if I get a 401 Unauthorized error? A: Check that $QODER_ACCESS_TOKEN is set correctly and has not expired. PAT users should create a replacement token; Service Account users should exchange the SA Key for a new SAT. Q: Why do I get a 400 Bad Request error when creating an agent? A: Check that the request body is valid JSON. Ensure the model field is a valid value (e.g., "ultimate") and that the tools field is an array. Q: Why is my session stuck in an idle state and not receiving events? A: A session is idle by default after creation. You must send a user.message event to trigger the agent. Ensure you have performed Step 5 correctly. Q: What should I do if the SSE stream connection is interrupted? A: We recommend saving the id of the last event received before the disconnection (e.g., evt_...). When reconnecting, include the ?after_id=<last_event_id> query parameter. The server will then resume sending events from where you left off. Q: Why doesGET /environmentsreturn an empty array? A: New accounts may not have a pre-configured environment. Create one as described in Step 2.

Next steps

Define an agent — Learn about all agent configuration fields.
Cloud environments — Customize your runtime environments.
Start a session — Dive deeper into session management.

​Prerequisites

​Step 1: Obtain an access token

​Option 1: PAT (personal user)

​Option 2: SAT (Service Account Token)

​Step 2: Select an environment

​Step 3: Create an agent

​Step 4: Create a session

​Step 5: Send a message and receive events

​FAQ

​Next steps

Prerequisites

Step 1: Obtain an access token

Option 1: PAT (personal user)

Option 2: SAT (Service Account Token)

Step 2: Select an environment

Step 3: Create an agent

Step 4: Create a session

Step 5: Send a message and receive events

FAQ

Next steps