Skip to main content
Guides

Quickstart

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.

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 doesGET /environmentsreturn an empty array? A: New accounts may not have a pre-configured environment. Create one as described in Step 2.

Next steps

Guides
Tutorials
API Reference