chenhg5-cc-connect/docs/management-api.md

cc-connect Management API Specification

Version: 1.1-draft
Status: Draft — subject to change before implementation
Last Updated: 2026-03-24

---

1. Overview

The cc-connect Management API is an HTTP-based REST API that enables external applications (web dashboards, TUI clients, GUI desktop apps, Mac tray apps) to manage and monitor cc-connect instances. It complements the existing internal Unix socket API by providing a network-accessible, token-authenticated interface suitable for remote and local management tools.

1.1 Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         cc-connect Process                               │
│                                                                          │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
│  │  Unix Socket API │    │  Management API   │    │  Bridge Server   │  │
│  │  (internal)      │    │  (HTTP :9820)     │    │  (WebSocket)     │  │
│  └────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘  │
│           │                       │                       │             │
│           └───────────────────────┼───────────────────────┘             │
│                                   │                                      │
│                          ┌────────┴────────┐                            │
│                          │  Core Engine(s)  │                            │
│                          │  Projects       │                            │
│                          │  Sessions      │                            │
│                          │  Cron/Heartbeat │                            │
│                          └─────────────────┘                            │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
     ┌────────┴────────┐   ┌───────┴───────┐   ┌─────────┴─────────┐
     │  Web Dashboard  │   │  TUI Client   │   │  Mac Tray App      │
     └─────────────────┘   └───────────────┘   └────────────────────┘

1.2 Design Principles

• RESTful: Resource-oriented URLs, standard HTTP methods
• JSON: All request/response bodies use application/json
• Consistent envelope: Every response uses {"ok": true|false, "data"|"error": ...}
• Token auth: Bearer token or query parameter for all endpoints

---

2. Configuration

2.1 Management Block

Add the following to config.toml:

[management]
enabled = true
port = 9820
token = "mgmt-secret"

Field	Type	Default	Description
enabled	boolean	false	Enable the Management API server
port	integer	9820	TCP port to listen on
token	string	(required)	Shared secret for authentication

When enabled is false, the Management API is not started. The token should be a strong, random string (e.g. 32+ characters).

2.2 Base URL

All endpoints are relative to:

http://<host>:<port>/api/v1

Example: http://localhost:9820/api/v1/status

---

3. Authentication

Every request must include a valid token. Two methods are supported:

3.1 Bearer Token (Recommended)

Authorization: Bearer <token>

Example:

curl -H "Authorization: Bearer mgmt-secret" http://localhost:9820/api/v1/status

3.2 Query Parameter

GET /api/v1/status?token=mgmt-secret

Note: Query parameter auth is provided for environments where setting headers is difficult. Prefer Bearer token for security (tokens in URLs may be logged).

3.3 Unauthorized Response

If the token is missing or invalid:

• HTTP Status: 401 Unauthorized
• Body:

{
  "ok": false,
  "error": "unauthorized: missing or invalid token"
}

---

4. Response Format

4.1 Success

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

4.2 Error

{
  "ok": false,
  "error": "human-readable error message"
}

4.3 HTTP Status Codes

Code	Meaning
200	Success
400	Bad request (invalid body, missing params)
401	Unauthorized (missing/invalid token)
404	Resource not found (project, session, etc.)
405	Method not allowed
500	Internal server error

---

5. Endpoint Reference

5.1 System

GET /api/v1/status

Returns system status and summary.

Response:

{
  "ok": true,
  "data": {
    "version": "v1.2.0",
    "uptime_seconds": 3600,
    "connected_platforms": ["feishu", "telegram"],
    "projects_count": 2,
    "bridge_adapters": [
      {
        "platform": "custom",
        "project": "my-backend",
        "capabilities": ["text", "images"]
      }
    ]
  }
}

Field	Type	Description
version	string	cc-connect version (e.g. v1.2.0)
uptime_seconds	number	Process uptime in seconds
connected_platforms	string[]	Platform types currently connected
projects_count	number	Number of configured projects
bridge_adapters	array	External adapters connected via Bridge WebSocket

---

POST /api/v1/restart

Triggers a graceful restart. The process will shut down cleanly and exec itself. A "restart successful" message may be sent to the session that initiated the restart (if applicable).

Request body (optional):

{
  "session_key": "telegram:123:456",
  "platform": "telegram"
}

If provided, the restart notification will be sent to the specified session after the new process starts.

Response:

{
  "ok": true,
  "data": {
    "message": "restart initiated"
  }
}

---

POST /api/v1/reload

Reloads configuration from disk without restarting the process. New projects may be added; removed projects are stopped. Changed project settings take effect.

Response:

{
  "ok": true,
  "data": {
    "message": "config reloaded",
    "projects_added": ["new-project"],
    "projects_removed": [],
    "projects_updated": ["my-backend"]
  }
}

---

GET /api/v1/config

Returns the current configuration with secrets redacted. Useful for debugging and UI display.

Query parameters: None

Response:

{
  "ok": true,
  "data": {
    "data_dir": "/home/user/.cc-connect",
    "language": "en",
    "projects": [
      {
        "name": "my-backend",
        "agent": {
          "type": "claudecode",
          "providers": [
            {
              "name": "anthropic",
              "api_key": "***",
              "base_url": "",
              "model": "claude-sonnet-4-20250514"
            }
          ]
        },
        "platforms": [
          {
            "type": "feishu",
            "options": {
              "app_id": "***",
              "app_secret": "***"
            }
          }
        ]
      }
    ]
  }
}

Secrets (e.g. api_key, token, app_secret, client_secret) are replaced with "***".

---

GET /api/v1/logs

Returns recent log entries.

Query parameters:

Param	Type	Default	Description
level	string	info	Minimum level: debug, info, warn, error
limit	int	100	Max entries to return (1–1000)

Response:

{
  "ok": true,
  "data": {
    "entries": [
      {
        "time": "2026-03-10T10:30:00Z",
        "level": "info",
        "message": "api server started",
        "attrs": {"socket": "/home/user/.cc-connect/run/api.sock"}
      }
    ]
  }
}

---

5.2 Projects

GET /api/v1/projects

Lists all projects with a summary.

Response:

{
  "ok": true,
  "data": {
    "projects": [
      {
        "name": "my-backend",
        "agent_type": "claudecode",
        "platforms": ["feishu", "telegram"],
        "sessions_count": 3,
        "heartbeat_enabled": true
      }
    ]
  }
}

---

GET /api/v1/projects/{name}

Returns detailed information for a single project.

Path parameters:

Param	Type	Description
name	string	Project name

Response:

{
  "ok": true,
  "data": {
    "name": "my-backend",
    "agent_type": "claudecode",
    "platforms": [
      {
        "type": "feishu",
        "connected": true
      },
      {
        "type": "telegram",
        "connected": true
      }
    ],
    "sessions_count": 3,
    "active_session_keys": ["telegram:123:456", "feishu:ou_xxx:chat_xxx"],
    "heartbeat": {
      "enabled": true,
      "paused": false,
      "interval_mins": 30,
      "session_key": "telegram:123:456"
    },
    "settings": {
      "quiet": false,
      "admin_from": "user1,user2",
      "language": "en",
      "disabled_commands": ["restart", "upgrade"]
    }
  }
}

Error (404):

{
  "ok": false,
  "error": "project not found: my-backend"
}

---

PATCH /api/v1/projects/{name}

Updates project settings. Only provided fields are updated.

Request body:

{
  "quiet": true,
  "admin_from": "user1,user2,user3",
  "language": "zh",
  "disabled_commands": ["restart", "upgrade", "cron"]
}

Field	Type	Description
quiet	boolean	Suppress thinking/tool progress messages
admin_from	string	Comma-separated user IDs for privileged commands; "*" = all
language	string	UI language: en, zh, zh-TW, ja, es
disabled_commands	string[]	Commands to disable (e.g. restart, upgrade, cron)

Response:

{
  "ok": true,
  "data": {
    "name": "my-backend",
    "settings": {
      "quiet": true,
      "admin_from": "user1,user2,user3",
      "language": "zh",
      "disabled_commands": ["restart", "upgrade", "cron"]
    }
  }
}

---

5.3 Sessions

Sessions are conversation contexts within a project. A session is identified by a session_key (format: platform:chatId:userId) and optionally by an internal id for named sessions (e.g. /new work creates a named session).

GET /api/v1/projects/{name}/sessions

Lists sessions for a project with summary info including the last message preview.

Response:

{
  "ok": true,
  "data": {
    "sessions": [
      {
        "id": "sess_abc123",
        "session_key": "telegram:123:456",
        "name": "work",
        "platform": "telegram",
        "agent_type": "claudecode",
        "active": true,
        "live": true,
        "history_count": 12,
        "created_at": "2026-03-10T09:00:00Z",
        "updated_at": "2026-03-10T10:30:00Z",
        "last_message": {
          "role": "assistant",
          "content": "Done! The tests are passing now...",
          "timestamp": "2026-03-10T10:30:00Z"
        },
        "user_name": "Alice",
        "chat_name": "dev-channel"
      }
    ],
    "active_keys": {
      "telegram:123:456": "telegram"
    }
  }
}

Field	Type	Description
active	boolean	Whether this is the selected session for its user key
live	boolean	Whether there is a running agent process for this session
last_message	object	Preview of the last message (role, content truncated to 200 chars, timestamp). null if no history.
user_name	string	Display name of the user (from platform metadata)
chat_name	string	Name of the chat/channel (from platform metadata)
active_keys	object	Map of session keys with active agent connections → platform name

---

POST /api/v1/projects/{name}/sessions

Creates a new session.

Request body:

{
  "session_key": "telegram:123:456",
  "name": "work"
}

Field	Type	Required	Description
session_key	string	yes	Platform routing key (e.g. telegram:123:456)
name	string	no	Human-readable session name

Response:

{
  "ok": true,
  "data": {
    "id": "sess_xyz789",
    "session_key": "telegram:123:456",
    "name": "work",
    "created_at": "2026-03-10T10:35:00Z"
  }
}

---

GET /api/v1/projects/{name}/sessions/{id}

Returns session detail including message history.

Path parameters:

Param	Type	Description
name	string	Project name
id	string	Session ID

Query parameters:

Param	Type	Default	Description
history_limit	int	50	Max history entries to return

Response:

{
  "ok": true,
  "data": {
    "id": "sess_abc123",
    "session_key": "telegram:123:456",
    "name": "work",
    "platform": "telegram",
    "agent_type": "claudecode",
    "agent_session_id": "as_xxx",
    "active": true,
    "live": true,
    "history_count": 12,
    "created_at": "2026-03-10T09:00:00Z",
    "updated_at": "2026-03-10T10:30:00Z",
    "history": [
      {
        "role": "user",
        "content": "Hello",
        "timestamp": "2026-03-10T09:00:05Z"
      },
      {
        "role": "assistant",
        "content": "Hi! How can I help?",
        "timestamp": "2026-03-10T09:00:10Z"
      }
    ]
  }
}

Field	Type	Description
live	boolean	Whether the session has an active agent process (can receive messages via /send)

---

DELETE /api/v1/projects/{name}/sessions/{id}

Deletes a session and its history.

Response:

{
  "ok": true,
  "data": {
    "message": "session deleted"
  }
}

---

POST /api/v1/projects/{name}/sessions/switch

Switches the active session for a given session_key (e.g. when a user has multiple named sessions).

Request body:

{
  "session_key": "telegram:123:456",
  "session_id": "sess_xyz789"
}

Field	Type	Required	Description
session_key	string	yes	Platform routing key
session_id	string	yes	Session ID to make active

Response:

{
  "ok": true,
  "data": {
    "message": "active session switched",
    "active_session_id": "sess_xyz789"
  }
}

---

POST /api/v1/projects/{name}/send

Sends a message to a session. The message is delivered to the agent as if the user had sent it via the platform. Requires the session to be live (i.e., have an active agent process). Check the live field from session detail to verify before sending.

Request body:

{
  "session_key": "telegram:123:456",
  "message": "Review the latest commit"
}

Field	Type	Required	Description
session_key	string	yes	Platform routing key
message	string	yes	Text to send to the agent

Response:

{
  "ok": true,
  "data": {
    "message": "message sent"
  }
}

---

5.4 Providers

Providers are API backends (e.g. Anthropic, OpenAI, custom endpoints) that supply the AI model for a project's agent.

GET /api/v1/projects/{name}/providers

Lists providers with active indicator.

Response:

{
  "ok": true,
  "data": {
    "providers": [
      {
        "name": "anthropic",
        "active": true,
        "model": "claude-sonnet-4-20250514",
        "base_url": ""
      },
      {
        "name": "relay",
        "active": false,
        "model": "claude-sonnet-4-20250514",
        "base_url": "https://api.relay.example.com"
      }
    ],
    "active_provider": "anthropic"
  }
}

---

POST /api/v1/projects/{name}/providers

Adds a new provider.

Request body:

{
  "name": "relay",
  "api_key": "sk-xxx",
  "base_url": "https://api.relay.example.com",
  "model": "claude-sonnet-4-20250514",
  "thinking": "disabled",
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_PROFILE": "bedrock"
  }
}

Field	Type	Required	Description
name	string	yes	Provider identifier
api_key	string	no*	API key (*required if no env)
base_url	string	no	Custom API endpoint
model	string	no	Model override
thinking	string	no	"disabled" for providers without adaptive thinking
env	object (k/v)	no	Extra environment variables

Response:

{
  "ok": true,
  "data": {
    "name": "relay",
    "message": "provider added"
  }
}

---

DELETE /api/v1/projects/{name}/providers/{provider}

Removes a provider. The active provider cannot be removed; switch first.

Response:

{
  "ok": true,
  "data": {
    "message": "provider removed"
  }
}

Error (400):

{
  "ok": false,
  "error": "cannot remove active provider; switch to another first"
}

---

POST /api/v1/projects/{name}/providers/{provider}/activate

Switches the active provider.

Response:

{
  "ok": true,
  "data": {
    "active_provider": "relay",
    "message": "provider activated"
  }
}

---

GET /api/v1/projects/{name}/models

Lists available models for the project's agent type.

Response:

{
  "ok": true,
  "data": {
    "models": [
      "claude-sonnet-4-20250514",
      "claude-3-5-sonnet-20241022",
      "claude-3-opus-20240229"
    ],
    "current": "claude-sonnet-4-20250514"
  }
}

---

POST /api/v1/projects/{name}/model

Sets the model for the project.

Request body:

{
  "model": "claude-3-5-sonnet-20241022"
}

Response:

{
  "ok": true,
  "data": {
    "model": "claude-3-5-sonnet-20241022",
    "message": "model updated"
  }
}

---

5.5 Cron Jobs

GET /api/v1/cron

Lists all cron jobs, optionally filtered by project.

Query parameters:

Param	Type	Description
project	string	Filter by project

Response:

{
  "ok": true,
  "data": {
    "jobs": [
      {
        "id": "cron_abc123",
        "project": "my-backend",
        "session_key": "telegram:123:456",
        "cron_expr": "0 6 * * *",
        "prompt": "Summarize GitHub trending",
        "exec": "",
        "work_dir": "",
        "description": "Daily GitHub Trending",
        "enabled": true,
        "silent": true,
        "created_at": "2026-03-10T08:00:00Z",
        "last_run": "2026-03-10T06:00:00Z",
        "last_error": ""
      }
    ]
  }
}

---

POST /api/v1/cron

Adds a cron job. Either prompt or exec must be provided, not both.

Request body (prompt job):

{
  "project": "my-backend",
  "session_key": "telegram:123:456",
  "cron_expr": "0 6 * * *",
  "prompt": "Summarize GitHub trending",
  "description": "Daily GitHub Trending",
  "silent": true
}

Request body (exec job):

{
  "project": "my-backend",
  "session_key": "telegram:123:456",
  "cron_expr": "0 9 * * 1",
  "exec": "npm run weekly-report",
  "work_dir": "/path/to/project",
  "description": "Weekly Report",
  "silent": false
}

Field	Type	Required	Description
project	string	no*	Project name (*required if multiple projects)
session_key	string	yes	Target session for prompt jobs
cron_expr	string	yes	Cron expression (5 or 6 fields)
prompt	string	no*	Prompt to send (*required if no exec)
exec	string	no*	Shell command (*required if no prompt)
work_dir	string	no	Working directory for exec
description	string	no	Human-readable label
silent	boolean	no	Suppress start notification
session_mode	string	no	reuse (default) or new_per_run — new agent session each run
timeout_mins	int	no	Scheduler wait per run: omit = 30 min, 0 = no time limit

Response:

{
  "ok": true,
  "data": {
    "id": "cron_xyz789",
    "project": "my-backend",
    "session_key": "telegram:123:456",
    "cron_expr": "0 6 * * *",
    "prompt": "Summarize GitHub trending",
    "description": "Daily GitHub Trending",
    "enabled": true,
    "created_at": "2026-03-10T10:40:00Z"
  }
}

---

DELETE /api/v1/cron/{id}

Deletes a cron job.

Response:

{
  "ok": true,
  "data": {
    "message": "cron job deleted"
  }
}

POST /api/v1/cron/{id}/exec

Triggers an existing cron job immediately. Disabled jobs can still be triggered manually. /api/v1/cron/{id}/run is accepted as a compatibility alias.

Response:

{
  "ok": true,
  "data": {
    "id": "cron_xyz789",
    "status": "triggered"
  }
}

---

5.6 Heartbeat

Heartbeat runs periodic prompts in a session (e.g. "check inbox") to keep the agent aware of the environment.

GET /api/v1/projects/{name}/heartbeat

Returns heartbeat status.

Response:

{
  "ok": true,
  "data": {
    "enabled": true,
    "paused": false,
    "interval_mins": 30,
    "only_when_idle": true,
    "session_key": "telegram:123:456",
    "silent": true,
    "run_count": 42,
    "error_count": 0,
    "skipped_busy": 5,
    "last_run": "2026-03-10T10:00:00Z",
    "last_error": ""
  }
}

---

POST /api/v1/projects/{name}/heartbeat/pause

Pauses heartbeat.

Response:

{
  "ok": true,
  "data": {
    "message": "heartbeat paused"
  }
}

---

POST /api/v1/projects/{name}/heartbeat/resume

Resumes heartbeat.

Response:

{
  "ok": true,
  "data": {
    "message": "heartbeat resumed"
  }
}

---

POST /api/v1/projects/{name}/heartbeat/run

Triggers heartbeat immediately (one-shot).

Response:

{
  "ok": true,
  "data": {
    "message": "heartbeat triggered"
  }
}

---

POST /api/v1/projects/{name}/heartbeat/interval

Sets the heartbeat interval.

Request body:

{
  "minutes": 15
}

Response:

{
  "ok": true,
  "data": {
    "interval_mins": 15,
    "message": "interval updated"
  }
}

---

5.7 Bridge

GET /api/v1/bridge/adapters

Lists connected bridge adapters (external platforms via WebSocket).

Response:

{
  "ok": true,
  "data": {
    "adapters": [
      {
        "platform": "custom",
        "project": "my-backend",
        "capabilities": ["text", "images", "files"],
        "connected_at": "2026-03-10T09:00:00Z"
      }
    ]
  }
}

---

6. Error Handling Conventions

6.1 Standard Error Response

All errors use the same envelope:

{
  "ok": false,
  "error": "human-readable message"
}

6.2 Common Errors

HTTP	Error message example	Cause
400	"project is required (multiple projects)"	Missing required parameter
400	"either prompt or exec is required"	Invalid cron job body
401	"unauthorized: missing or invalid token"	Auth failure
404	"project not found: xyz"	Unknown project/session/cron
404	"session not found"	Unknown session ID
405	"method not allowed"	Wrong HTTP method
500	"internal error"	Unexpected server error

6.3 Validation Errors

When request body validation fails:

{
  "ok": false,
  "error": "invalid request: session_key is required"
}

---

7. Session Key Format

The session_key is a composite identifier used to route messages to the correct platform and chat:

<platform>:<chat_id>:<user_id>

Examples:

• telegram:123456789:123456789 — Telegram user 123456789 in chat 123456789
• feishu:ou_xxx:chat_yyy — Feishu user in chat
• slack:C01234:U05678 — Slack channel and user
• discord:123456789:987654321 — Discord guild and user

For multi-workspace mode, the format may include a workspace prefix:

<workspace>:<platform>:<chat_id>:<user_id>

---

8. CORS

When the Management API is used by web dashboards, CORS headers should be configurable. A suggested config extension:

[management]
enabled = true
port = 9820
token = "mgmt-secret"
cors_origins = ["http://localhost:3000", "https://dashboard.example.com"]

If not configured, CORS may be disabled or use a default (e.g. * for same-origin only).

---

9. Changelog

Version	Date	Changes
1.1-draft	2026-03-24	Enrich session list/detail with live, last_message, agent_type, user_name, chat_name, active_keys fields
1.0-draft	2026-03-10	Initial specification

---

10. References

• Bridge Protocol — WebSocket protocol for external platform adapters
• Usage Guide — End-user features and slash commands
• config.example.toml — Configuration template