All Products
Search
Document Center

:Quickstart

Last Updated:Sep 24, 2026

Get your first Qoder Cloud Agent running in 5 steps: get a token, select an environment, create an agent, create a session, and send and receive messages. All you need is curl—no SDK installation is required.

Important

The new Qoder CN documentation site is now available. Content on this site may not reflect the latest product features and changes. Visit docs.qoder.cn for the latest product documentation.

Prerequisites

  • A Qoder account

  • A terminal environment (macOS, Linux, or WSL)

  • curl and jq (optional, for formatting JSON output)

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_PAT="your-token", use curl.exe to bypass PowerShell's curl alias, and install jq separately (e.g., winget install jqlang.jq).

Step 1: Get a PAT

  1. Sign in to the Qoder Console.

  2. Navigate to Settings > Personal Access Tokens.

  3. Click **Create Token**, then set a name and expiration.

  4. Copy the token and set it as an environment variable:

export QODER_PAT="your-token-here"

Your token is shown only once upon creation. Save it to a safe place immediately. For convenience, add the export command to your shell's startup file, such as ~/.bashrc or ~/.zshrc.

Step 2: Select an environment

List your available environments to get an environment ID:

curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq .

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

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "config": {"type": "cloud", "networking": {"type": "unrestricted"}}}' | jq .

Step 3: Create an agent

Define a general-purpose agent with shell tools:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -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 https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -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 "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -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 "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

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 the $QODER_PAT environment variable is set correctly and your token has not expired. If needed, create a new token and update the environment variable.

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 does GET /environments return an empty array?

A: New accounts may not have a pre-configured environment. Create one as described in Step 2.