AGTerm
API Reference

API Reference

Complete REST and WebSocket API reference for AGTerm.

Base URL 

http://localhost:3000/api

All endpoints return JSON with this structure:

{
  "success": true,
  "data": { ... }
}

Or on error:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Sessions API

List Sessions 

GET /api/sessions

Returns all active sessions.

Response:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "My Session",
        "agent": "agterm",
        "createdAt": "2024-01-15T10:30:00Z",
        "lastActiveAt": "2024-01-15T11:45:00Z",
        "workspaceDir": "/home/user/.agterm/workspaces/550e8400...",
        "pid": 12345,
        "modelConfig": {
          "provider": "anthropic",
          "model": "claude-sonnet-4-20250514"
        }
      }
    ]
  }
}

Create Session 

POST /api/sessions
Content-Type: application/json

{
  "name": "My Session",
  "agent": "agterm",
  "provider": "groq",
  "model": "llama-3.3-70b-versatile"
}

Parameters:

FieldTypeRequiredDescription
namestringNoSession display name
agentstringYesAgent type: agterm, claude, gemini, codex, shell
providerstringNoLLM provider override
modelstringNoModel name override

Response: 201 Created

{
  "success": true,
  "data": {
    "session": { ... }
  }
}

Get Session 

GET /api/sessions/:id

Delete Session 

DELETE /api/sessions/:id

Terminates the session and cleans up workspace.

Switch Agent 

POST /api/sessions/:id/switch-agent
Content-Type: application/json

{
  "agent": "claude"
}

Send Input 

POST /api/sessions/:id/input
Content-Type: application/json

{
  "data": "Hello, world!\n"
}

Send terminal input to a session. Useful for programmatic interaction.

Resize Terminal 

POST /api/sessions/:id/resize
Content-Type: application/json

{
  "cols": 120,
  "rows": 40
}

Get Git Status 

GET /api/sessions/:id/git

Returns git status for the session’s workspace:

{
  "success": true,
  "data": {
    "status": {
      "isRepo": true,
      "branch": "main",
      "ahead": 2,
      "behind": 0,
      "staged": 1,
      "unstaged": 3,
      "untracked": 0
    },
    "formatted": "main ↑2 +1 ~3",
    "workspaceDir": "/home/user/.agterm/workspaces/..."
  }
}

Agents API

List Agents 

GET /api/agents

Returns all available agents with their status:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agterm",
        "name": "AGTerm",
        "icon": "agterm",
        "color": "#58a6ff",
        "welcome": "AGTerm agent ready.",
        "command": "agterm-agent",
        "available": true,
        "cliExists": true,
        "cliPath": "/usr/local/bin/agterm-agent",
        "hasCredentials": true,
        "keySource": "env"
      },
      {
        "id": "claude",
        "name": "Claude Code",
        "available": false,
        "cliExists": true,
        "hasCredentials": false,
        "missingEnvVars": ["ANTHROPIC_API_KEY"]
      }
    ]
  }
}

Get Agent 

GET /api/agents/:id

Models API

List All Models 

GET /api/models

Returns all providers and their available models:

{
  "success": true,
  "data": {
    "providers": [
      {
        "id": "anthropic",
        "name": "Anthropic",
        "configured": true,
        "models": [
          {
            "id": "claude-opus-4-20250514",
            "name": "Claude Opus 4",
            "description": "Most capable reasoning model"
          }
        ]
      }
    ],
    "profiles": [...],
    "configuredProviders": ["anthropic", "groq"]
  }
}

List Profiles 

GET /api/models/profiles

List Configured Providers 

GET /api/models/providers

Get Agent Models 

GET /api/models/agent/:agent

Returns models available for a specific agent type.

Files API

List Directory 

GET /api/files/list?path=/home/user&hidden=true

Query Parameters:

ParamTypeDefaultDescription
pathstringcwdDirectory to list
hiddenbooleanfalseInclude hidden files

Read File 

GET /api/files/read?path=/home/user/file.txt

Maximum file size: 1MB.

Write File 

POST /api/files/write
Content-Type: application/json

{
  "path": "/home/user/file.txt",
  "content": "File contents here"
}

Create Directory 

POST /api/files/mkdir
Content-Type: application/json

{
  "path": "/home/user/new-dir"
}

Delete File 

DELETE /api/files/delete?path=/home/user/file.txt

Rename/Move 

POST /api/files/rename
Content-Type: application/json

{
  "oldPath": "/home/user/old.txt",
  "newPath": "/home/user/new.txt"
}

Recordings API

List Recordings 

GET /api/recordings

Get Recording 

GET /api/recordings/:id

Delete Recording 

DELETE /api/recordings/:id

Start Recording 

POST /api/recordings/start/:sessionId

Stop Recording 

POST /api/recordings/stop/:sessionId

Get Recording Status 

GET /api/recordings/status/:sessionId

Costs API

Cost Dashboard 

GET /api/costs/dashboard?startDate=2024-01-01&endDate=2024-01-31

Session Costs 

GET /api/costs/sessions
GET /api/costs/sessions/:sessionId

Provider Breakdown 

GET /api/costs/providers

Daily Costs 

GET /api/costs/daily?days=30

Health API 

GET /api/health

Response:

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2024-01-15T12:00:00Z"
}

WebSocket API

Connect to the WebSocket server:

ws://localhost:3000/ws?token=<jwt_token>

Message Format

All messages are JSON:

{
  "type": "message_type",
  "sessionId": "optional-session-id",
  "payload": { ... }
}

Session Messages

Attach to Session 

{
  "type": "session:attach",
  "payload": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "cols": 120,
    "rows": 40
  }
}

Response: session:attached

Detach from Session 

{
  "type": "session:detach"
}

Response: session:detached

Terminal Messages

Send Input 

{
  "type": "terminal:input",
  "payload": {
    "data": "ls -la\n"
  }
}

Receive Output 

{
  "type": "terminal:output",
  "sessionId": "...",
  "payload": {
    "data": "total 48\ndrwxr-xr-x  12 user  staff   384 Jan 15 10:30 .\n..."
  }
}

Resize Terminal 

{
  "type": "terminal:resize",
  "payload": {
    "cols": 120,
    "rows": 40
  }
}

Agent Messages

Switch Agent 

{
  "type": "agent:switch",
  "payload": {
    "agent": "claude"
  }
}

Response: agent:switched with updated session data.

Utility Messages

Ping/Pong 

{ "type": "ping" }

Response: { "type": "pong" }

Error 

{
  "type": "error",
  "payload": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session not found"
  }
}

Common Error Codes

CodeDescription
INVALID_MESSAGEMalformed JSON
INVALID_REQUESTMissing required field
SESSION_NOT_FOUNDSession doesn’t exist
AGENT_NOT_FOUNDInvalid agent type
AGENT_DISABLEDAgent is disabled (e.g., shell)
NO_SESSIONNot attached to any session
ATTACH_FAILEDFailed to attach to session

Rate Limiting

Default limits:

  • Window: 15 minutes
  • Max requests: 100 per window

Configure via environment variables:

  • AGTERM_RATE_LIMIT_WINDOW (ms)
  • AGTERM_RATE_LIMIT_MAX

Related Documentation

Configuration
Environment variables
Agents
Agent types and capabilities
Getting Started
Quick start guide
Model GatewayConfiguration