Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

Get your first Qoder Cloud Agent running in five steps: obtain a token, pick an environment, create an Agent, start a Session, and exchange messages. The whole flow uses only curl — no SDK required.

​
Prerequisites

  • A Qoder account
  • A terminal (macOS, Linux, or WSL)
  • curl, plus jq (optional, for formatting JSON)

​
Step 1: Obtain a PAT

  1. Sign in to the Qoder console.
  2. Open “Settings → Personal Access Tokens”.
  3. Click “Create Token”, set a name and expiration.
  4. Copy the token and export it as an environment variable:
# Export the PAT so the rest of the commands can read it
export QODER_PAT="your-personal-access-token"
The token is shown only once at creation. Save it immediately — adding it to ~/.bashrc or ~/.zshrc is recommended.

​
Step 2: Pick an Environment

List the available environments and capture the default ID: 
# List all available environments
curl -s https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"
Example response: 
{
  "data": [
    {
      "id": "env_default",
      "name": "default",
      "config": {
        "type": "cloud",
        "networking": "unrestricted"
      },
      "status": "ready",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "first_id": "env_default",
  "last_id": "env_default",
  "has_more": false
}

# Extract the default environment ID
ENV_ID=$(curl -s https://openapi.qoder.sh/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.data[0].id')

echo "Environment ID: $ENV_ID"

​
Step 3: Create an Agent

Define a general-purpose Agent with a shell tool: 
# Create the Agent — returns 201
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "You are an efficient programming assistant skilled at writing code and troubleshooting issues.",
    "tools": [
      {"type": "bash_20250124"}
    ]
  }' | jq .
Example response: 
{
  "id": "ag_abc123def456",
  "name": "my-first-agent",
  "model": "ultimate",
  "system": "You are an efficient programming assistant skilled at writing code and troubleshooting issues.",
  "tools": [{"type": "bash_20250124"}],
  "metadata": {},
  "version": 1,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

# Extract the Agent ID
AGENT_ID=$(curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "model": "ultimate",
    "system": "You are an efficient programming assistant.",
    "tools": [{"type": "bash_20250124"}]
  }' | jq -r '.id')

echo "Agent ID: $AGENT_ID"

​
Step 4: Start a Session

Bind the Agent to the Environment to create a runtime instance: 
# Start a Session — returns 201
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\"
  }" | jq .
Example response: 
{
  "id": "ses_xyz789",
  "agent_id": "ag_abc123def456",
  "environment_id": "env_default",
  "status": "idle",
  "title": null,
  "metadata": {},
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "created_at": "2026-05-18T10:01:00Z",
  "updated_at": "2026-05-18T10:01:00Z"
}

# Extract the Session ID
SESSION_ID=$(curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')

echo "Session ID: $SESSION_ID"

​
Step 5: Send a Message and Stream Events

Send a user message to the Session, then receive Agent responses live over SSE: 
# Send a message
curl -s -X POST "https://openapi.qoder.sh/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": "Write a Python function that computes the Fibonacci sequence and run a test."
  }' | jq .

# Stream events over SSE
curl -s -N "https://openapi.qoder.sh/api/v1/cloud/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"
Example event stream output: 
event: session.status_rescheduled
data: {"type":"session.status_rescheduled","status":"processing"}

event: span.model_request_start
data: {"type":"span.model_request_start"}

event: agent.thinking
data: {"type":"agent.thinking","content":"Let me write a Fibonacci function..."}

event: agent.message
data: {"type":"agent.message","content":"Here is an implementation of the Fibonacci sequence: ..."}

event: session.status_idle
data: {"type":"session.status_idle","status":"idle"}

​
End-to-End Script

The whole flow combined into a single runnable script: 
#!/bin/bash
# Qoder Cloud Agents quickstart script
# Usage: export QODER_PAT="your-token" && bash quickstart.sh

set -euo pipefail

BASE_URL="https://openapi.qoder.sh/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

echo "=== Step 1: Fetch the default environment ==="
ENV_ID=$(curl -s "$BASE_URL/environments" "${HEADERS[@]}" | jq -r '.data[0].id')
echo "Environment ID: $ENV_ID"

echo "=== Step 2: Create the Agent ==="
AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "system": "You are an efficient programming assistant.",
    "tools": [{"type": "bash_20250124"}]
  }' | jq -r '.id')
echo "Agent ID: $AGENT_ID"

echo "=== Step 3: Start the Session ==="
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENV_ID\"}" | jq -r '.id')
echo "Session ID: $SESSION_ID"

echo "=== Step 4: Send a message ==="
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": "Print Hello World and tell me the current system time."
  }' | jq .

echo "=== Step 5: Stream events ==="
echo "(Press Ctrl+C to exit)"
curl -s -N "$BASE_URL/sessions/$SESSION_ID/events/stream" "${HEADERS[@]}"

​
FAQ

Q: I’m getting 401 Unauthorized. A: Check that $QODER_PAT is set correctly and the token has not expired. Recreate the token and update the environment variable. 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: Confirm you sent a user.message event. A new Session starts in idle and only begins processing once it receives a message. Q: My SSE stream disconnected. A: Reconnect to the events/stream endpoint. The stream resumes from the latest state. You can also poll GET /events to fetch historical events.

​
Next Steps