ADBAgent API User Guide

Request example

curl -s "$BASE/api/v1/sessions" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response fields:

Response example:

{
  "sessions": [
    {
      "sessionId": "ses_xxxxx",
      "title": "My analysis task",
      "model": "adb-qwen3.5-plus/qwen3.5-plus",
      "createdAt": "2026-01-01T10:00:00.000Z",
      "updatedAt": "2026-01-01T12:00:00.000Z"
    }
  ]
}

Request parameters

Request example

curl -s "$BASE/api/v1/sessions/$SID/messages?limit=50" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response fields:

Response example:

{
  "messages": [
    {
      "role": "user",
      "content": "Analyze user activity trends for the past 7 days",
      "createdAt": "2026-01-01T10:00:00.000Z"
    },
    {
      "role": "assistant",
      "content": "Based on the analysis of the user_activity table...",
      "createdAt": "2026-01-01T10:00:05.000Z"
    }
  ]
}

Request example

curl -s -X POST "$BASE/api/v1/sessions/$SID/abort" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Returns HTTP 200 on success:

{"success": true}

Request example

curl -s -X DELETE "$BASE/api/v1/sessions/$SID" \
  -H "Authorization: Bearer $TOKEN"
# Returns HTTP 204

Response

Response fields:

Polling example script

The following script automates the polling loop:

poll_round() {
  local sid=$1 rid=$2
  while true; do
    RESP=$(curl -s "$BASE/api/v1/sessions/$sid/rounds/$rid" \
      -H "Authorization: Bearer $TOKEN")
    STATUS=$(echo "$RESP" | jq -r '.status')
    case $STATUS in
      completed)
        echo "$RESP" | jq '{question, answer, model, duration}'
        return 0 ;;
      error)
        echo "$RESP" | jq '{question, answer, status}'
        return 1 ;;
      *)
        sleep 2 ;;
    esac
  done
}

# Usage: send a prompt and wait for results
RID=$(curl -s -X POST "$BASE/api/v1/sessions/$SID/prompt" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Analyze user activity trends for the past 7 days"}' | jq -r '.roundId')
poll_round "$SID" "$RID"

Request parameters

Three output formats are supported:

Request example

Subscribe to the event stream first, then send the prompt.

# Typewriter effect in the terminal (plain format)
curl -N "$BASE/api/v1/sessions/$SID/events?format=plain" \
  -H "Authorization: Bearer $TOKEN"

Frontend integration example

The following JavaScript example consumes the SSE text format stream:

async function streamChat(base, token, sessionId, question) {
  const controller = new AbortController();

  // 1. Subscribe to the SSE stream
  const eventRes = await fetch(
    `${base}/api/v1/sessions/${sessionId}/events?format=text`,
    {
      headers: { 'Authorization': `Bearer ${token}` },
      signal: controller.signal
    }
  );

  // 2. Send the prompt
  await fetch(`${base}/api/v1/sessions/${sessionId}/prompt`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text: question })
  });

  // 3. Read the event stream
  const reader = eventRes.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  let answer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const chunks = buffer.split('\n\n');
    buffer = chunks.pop() ?? '';

    for (const chunk of chunks) {
      const dataLine = chunk.split('\n')
        .find(l => l.startsWith('data:'));
      if (!dataLine) continue;
      const event = JSON.parse(dataLine.slice(5).trim());

      if (event.type === 'delta') {
        answer += event.content ?? '';
        console.log(event.content);  // Real-time output
      } else if (event.type === 'done') {
        controller.abort();
        return answer;
      } else if (event.type === 'error') {
        throw new Error(event.message);
      }
    }
  }
  return answer;
}

Request example

curl -s "$BASE/api/v1/sessions/$SID/model" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response fields:

Response example:

{
  "sessionId": "ses_xxxxx",
  "model": "adb-qwen3.5-plus/qwen3.5-plus",
  "globalDefault": "adb-qwen3.5-plus/qwen3.5-plus",
  "effective": "adb-qwen3.5-plus/qwen3.5-plus"
}

Request parameters

Request example

curl -s -X POST "$BASE/api/v1/sessions/$SID/model" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"adb-qwen3.5-plus/qwen3.5-plus"}' | jq .

Response

Response example:

{
  "sessionId": "ses_xxxxx",
  "model": "adb-qwen3.5-plus/qwen3.5-plus",
  "globalDefault": "adb-qwen3.5-plus/qwen3.5-plus",
  "effective": "adb-qwen3.5-plus/qwen3.5-plus"
}

Request example

curl -s "$BASE/api/v1/datasources" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response fields:

Response example:

{
  "data_sources": [
    {
      "name": "adb_mysql_default",
      "type": "adb_mysql",
      "description": "",
      "enabled": true,
      "configured": true,
      "gateway_status": "running",
      "connection": {
        "host": "xxx",
        "port": 3306,
        "user": "xxx",
        "database": "xxx"
      }
    }
  ]
}

Request example

curl -s "$BASE/api/v1/datasources/adb_mysql_default" \
  -H "Authorization: Bearer $TOKEN" | jq .

Request example

curl -s "$BASE/api/v1/datasources/adb_mysql_default/databases" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response example:

{
  "databases": [
    "INFORMATION_SCHEMA",
    "my_database",
    "analytics_db"
  ]
}

Request parameters

Path parameters:

Request example

curl -s "$BASE/api/v1/datasources/adb_mysql_default/my_database/tables" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response example:

{
  "tables": ["orders", "users", "products"]
}

Request parameters

Request example

curl -s -X POST "$BASE/api/v1/datasources" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_datasource",
    "type": "adb_mysql",
    "connection": {
      "host": "xxx.xxx.xxx.xxx",
      "port": 3306,
      "user": "db_user",
      "password": "db_password",
      "database": "my_database"
    }
  }' | jq .

Request example

curl -s -X PUT "$BASE/api/v1/datasources/my_datasource" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "connection": {
      "host": "new-host.xxx.xxx",
      "port": 3306,
      "user": "new_user",
      "password": "new_password",
      "database": "new_database"
    }
  }' | jq .

Request example

curl -s -X DELETE "$BASE/api/v1/datasources/my_datasource" \
  -H "Authorization: Bearer $TOKEN"
# Returns HTTP 204

Request parameters

Request example

# Project-level skills only
curl -s "$BASE/api/v1/skills" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Include global skills
curl -s "$BASE/api/v1/skills?includeGlobal=true" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

Response fields:

Response example:

{
  "skills": [
    {
      "name": "alibabacloud-analyticdb-mysql-copilot",
      "description": "ADB MySQL database AI assistant",
      "scope": "project",
      "builtIn": true,
      "permission": "allow"
    }
  ],
  "total": 1
}

Request example

curl -s "$BASE/api/v1/skills/my-custom-skill" \
  -H "Authorization: Bearer $TOKEN" | jq .

Response

The content field in the response contains the full Markdown content of SKILL.md.

Request parameters

Request example

curl -s -X POST "$BASE/api/v1/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "adb-sql-review",
    "description": "ADB MySQL SQL review skill",
    "content": "# ADB SQL Review\n\n## When to use\nUse when reviewing SQL performance.\n\n## Rules\n1. Check for SELECT *\n2. Check for missing WHERE clauses\n"
  }' | jq .

Response

Response example:

{
  "name": "adb-sql-review",
  "action": "added",
  "path": "/path/.opencode/skills/adb-sql-review/SKILL.md"
}

The action field is added for new skills or updated for existing ones.

Request parameters

Permission values:

Request example

# Disable a skill
curl -s -X PATCH "$BASE/api/v1/skills/adb-sql-review/permission" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permission": "deny"}' | jq .

# Enable a skill
curl -s -X PATCH "$BASE/api/v1/skills/adb-sql-review/permission" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permission": "allow"}' | jq .

Request example

# Prepare and upload a skill ZIP
mkdir -p adb-sql-review
cat > adb-sql-review/SKILL.md << 'EOF'
---
name: adb-sql-review
description: ADB MySQL SQL review skill
---

# ADB SQL Review

## When to use
Use when reviewing SQL queries.
EOF

cd adb-sql-review && zip -r /tmp/adb-sql-review.zip . && cd -

# Upload to install
curl -s -X POST "$BASE/api/v1/skills/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/tmp/adb-sql-review.zip" | jq .

/api/v1/skills/install is equivalent to /api/v1/skills/upload — you can use either endpoint.

Request example

curl -s -o adb-sql-review.zip \
  "$BASE/api/v1/skills/adb-sql-review/download" \
  -H "Authorization: Bearer $TOKEN"

# Check contents
unzip -l adb-sql-review.zip

Request example

curl -s -X DELETE "$BASE/api/v1/skills/adb-sql-review" \
  -H "Authorization: Bearer $TOKEN"
# Returns HTTP 204