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.

This guide walks through the full Qoder Cloud Agents workflow with curl: create an Agent, start a Session, send a message, and consume the event stream.

​
Prerequisites

# Set the personal access token
export QODER_PAT="pt-your-token-here"

# API base URL
export BASE_URL="https://openapi.qoder.sh/api/v1/cloud"
Generate a PAT in the Qoder console under Personal Settings → Access Tokens.

​
Common header template

All requests must include: 
-H "Authorization: Bearer $QODER_PAT"
-H "Content-Type: application/json"

​
Step 1: Create an Agent

AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-assistant",
    "model": "ultimate",
    "system": "You are an efficient coding assistant. Reply concisely and clearly."
  }' | jq -r '.id')

echo "Agent ID: $AGENT_ID"

​
Step 2: Get an Environment

# List available environments and pick the first one
ENV_ID=$(curl -s "$BASE_URL/environments?limit=1" \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.data[0].id')

echo "Environment ID: $ENV_ID"

​
Step 3: Start a Session

SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\",
    \"title\": \"curl test session\"
  }" | jq -r '.id')

echo "Session ID: $SESSION_ID"

​
Step 4: Send a message

curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": "Write a quicksort function in Python."
      }
    ]
  }' | jq .

​
Step 5: Consume the SSE event stream

curl -N "$BASE_URL/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"
Each event is separated by a blank line: 
id: evt_019e392c0d787cfaa21bda98e06cd913
event: user.message
data: {"id":"evt_019e392c...","type":"user.message","content":"Write a quicksort function in Python.",...}

id: evt_771c1195bcbd4a07834d4ed4dd6450ca
event: session.status_rescheduled
data: {"id":"evt_771c1195...","type":"session.status_rescheduled",...}

id: evt_f8599c68e7784f2d8c490af1b3056716
event: agent.message
data: {"id":"evt_f8599c68...","type":"agent.message","content":[{"type":"text","text":"..."}],...}

id: evt_a289470296c94e7ba8d7ea562efe5925
event: session.status_idle
data: {"id":"evt_a28947...","type":"session.status_idle","stop_reason":{"type":"end_turn"},...}
The -N flag disables curl’s output buffering so SSE events appear in real time.

​
Resume after a disconnect

If the connection drops, resume from the last received event using after_id: 
LAST_EVT_ID="evt_a289470296c94e7ba8d7ea562efe5925"

curl -N "$BASE_URL/sessions/$SESSION_ID/events/stream?after_id=$LAST_EVT_ID" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"

​
Polling events (alternative to SSE)

If long-lived connections are unavailable, poll the events list: 
curl -s "$BASE_URL/sessions/$SESSION_ID/events?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

​
End-to-end script

The steps above combined into a single executable script: 
#!/usr/bin/env bash
set -euo pipefail

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

# Create Agent
AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" "${HEADERS[@]}" \
  -d '{"name":"quick-test","model":"ultimate","system":"You are an assistant."}' | jq -r '.id')
echo "Agent: $AGENT_ID"

# Get environment
ENV_ID=$(curl -s "$BASE_URL/environments?limit=1" "${HEADERS[@]}" | jq -r '.data[0].id')
echo "Environment: $ENV_ID"

# Create session
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" "${HEADERS[@]}" \
  -d "{\"agent\":\"$AGENT_ID\",\"environment_id\":\"$ENV_ID\"}" | jq -r '.id')
echo "Session: $SESSION_ID"

# Send message
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" "${HEADERS[@]}" \
  -d '{"events":[{"type":"user.message","content":"Hello!"}]}' > /dev/null
echo "Message sent"

# Consume event stream
echo "--- Event stream ---"
curl -N "$BASE_URL/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"