Skill: erview/copaw-api-chat (version 0.1.0)

--- name: copaw-api-chat description: "Communicate with a CoPaw instance through its HTTP API. Use when: (1) you need to inspect available CoPaw agents or chats, (2) create a chat or session and send a message via API, (3) understand CoPaw auth, scoping, or SSE behavior before integration work, (4) build wrappers, automations, or skills on top of CoPaw API." --- # CoPaw API Chat Use this skill to work with **CoPaw over HTTP API**, not through the web UI. ## When to use - You need to talk to a local CoPaw instance programmatically. - You need the correct sequence: **create chat/session → send message → read SSE**. - You need to understand agent scoping, auth layers, or related API groups before building automation. ## Workflow 1. Read `references/overview-auth-scoping.md` first. 2. If the task is about chatting with CoPaw, then read `references/chats-console-sse.md`. 3. If the task touches agent/model/skill/tool management, read `references/agents-models-skills-tools.md`. 4. If the task touches workspace, MCP, or cron, read `references/workspace-mcp-cron.md`. 5. If you need ready-to-run examples, read `references/practical-recipes.md`. ## Minimal practical path 1. Confirm agent id (`default` unless proven otherwise). 2. Create a chat with `POST /api/chats`. 3. Reuse the returned `session_id/user_id/channel` context. 4. Send the message with `POST /api/agents/{agentId}/console/chat`. 5. Read the response as **SSE**. ## Important rules - Do not assume stateless request/response. CoPaw is **chat/session-centric**. - Distinguish confirmed API behavior from interpretation. - Prefer agent-scoped routes (`/api/agents/{agentId}/...`) or set `X-Agent-Id` explicitly. - In the current deployment, auth may be provided by **nginx Basic Auth** even if internal CoPaw auth is off. - Treat `/api/workspace` and some `/api/agents/*/files/*` surfaces as dangerous/admin-level APIs. ## References - `references/overview-auth-scoping.md` — API surface, auth, scoping, priorities - `references/chats-console-sse.md` — chat lifecycle, session context, SSE mechanics - `references/agents-models-skills-tools.md` — management surfaces around agents/models/skills/tools - `references/workspace-mcp-cron.md` — workspace, MCP, cron boundaries and risks - `references/practical-recipes.md` — short request examples and file structure examples ## Output expectations When using this skill, answer with: - the minimal correct endpoint sequence, - the required payload shape, - auth/scoping caveats, - and only the API groups relevant to the task.

path: _meta.json
content: name: copaw-api-chat
version: 0.1.0
private: yes

path: references/agents-models-skills-tools.md
content: # Agents / Models / Skills / Tools

## /api/agents
Use when you need to inspect or manage available agents.
Practical value:
- list agents
- understand agent-scoped routing
- inspect default agent assumptions

## /api/models
Use when you need to understand provider/model configuration.
Practical value:
- confirm whether a working model/provider is configured
- inspect current model surface before blaming chat flow

## /api/skills
Use when you need to inspect or manage CoPaw skills.
Practical value:
- list skills
- understand enable/disable/install surfaces
- useful for future skill automation

## /api/tools
Use when you need tool inventory / toggling surfaces.
Practical value:
- inspect tool availability
- understand what the target CoPaw agent can actually do

## Caveats
- These are management surfaces, not the primary chat flow.
- For simple "talk to CoPaw" tasks, do not start here unless chat flow fails.
- Some of these are effectively admin surfaces and should not be used casually in automation.

## Confirmed
Confirmed by local CoPaw API research:
- `/api/agents`
- `/api/models`
- `/api/skills`
- `/api/tools`
all exist as practical API groups.


path: references/chats-console-sse.md
content: # Chats / Console Chat / SSE

## Core model
CoPaw chat flow is **session-centric**.

Correct sequence:
1. Create or select chat context
2. Reuse its `session_id / user_id / channel`
3. Send message through console chat endpoint
4. Read answer from SSE stream

## 1. Create chat
Endpoint:
- `POST /api/chats`

Minimal payload example:
```json
{
  "name": "neuromant-api-test",
  "session_id": "neuromant-api-session",
  "user_id": "neuromant",
  "channel": "console",
  "meta": {}
}
```

Server returns a `chat_id` and stores chat context.

## 2. Send message
Preferred endpoint:
- `POST /api/agents/{agentId}/console/chat`

Minimal payload pattern:
```json
{
  "channel": "console",
  "user_id": "api-user",
  "session_id": "api-session",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Hello. Reply with one short sentence."}
      ]
    }
  ]
}
```

## 3. Read answer
This endpoint returns **SSE** (`text/event-stream`).
Expect `data: <json>` frames.
Typical object flow:
- `response`
- `message`
- `content`

## 4. Stop / control
There is a stop path for long-running chat work:
- `POST /api/console/chat/stop?chat_id=<chat_id>`

## Important caveats
- Do not assume a single stateless prompt request is enough.
- If you skip chat/session creation, the request may connect but not behave as expected.
- The most important context fields are:
  - `session_id`
  - `user_id`
  - `channel`

## Confirmed vs interpretation
Confirmed:
- `/api/chats` exists
- `/api/console/chat` exists
- SSE is used for response streaming
- chat-first flow is the safest integration pattern

Interpretation:
- for reliable automation, chat creation should be treated as mandatory, even if some UI paths may hide it implicitly
e UI paths may hide it implicitly


path: references/overview-auth-scoping.md
content: # Overview / Auth / Scoping

## What is confirmed
- CoPaw exposes API under `/api/*`.
- Current deployment may put **nginx Basic Auth** in front of CoPaw.
- CoPaw also has optional internal auth (`Bearer`) when `COPAW_AUTH_ENABLED=true`.
- Many routes are **agent-scoped**:
  - path form: `/api/agents/{agentId}/...`
  - header form: `X-Agent-Id: <agentId>`
  - fallback: active/default agent

## Practical guidance
- For automation, prefer `/api/agents/{agentId}/...`.
- If there is any ambiguity, set agent explicitly and do not rely on implicit default resolution.
- In the current setup, requests may need nginx Basic Auth even if internal Bearer auth is off.

## Relevant API groups
- `/api/chats`
- `/api/console/chat`
- `/api/skills`
- `/api/tools`
- `/api/models`
- `/api/workspace`
- `/api/mcp`
- `/api/cron`
- `/api/agents`

## Interpretation boundary
Confirmed:
- `/api/*` surface exists
- agent-scoped routing exists
- external auth in front of CoPaw is possible

Interpretation:
- for robust integrations, explicit scoping is safer than default-agent behavior
ior
safer than default-agent behavior


path: references/practical-recipes.md
content: # Practical Recipes

## Minimal sequence
1. List agents
2. Create chat
3. Send message to agent-scoped console chat endpoint
4. Read SSE answer

## Example request flow

### List agents
```bash
curl -s http://COPAW_HOST:PORT/api/agents
```

### Create chat
```bash
curl -s -X POST http://127.0.0.1:8088/api/chats \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "neuromant-api-test",
    "session_id": "neuromant-api-session",
    "user_id": "neuromant",
    "channel": "console",
    "meta": {}
  }'
```

### Send message
```bash
curl -sN -X POST http://127.0.0.1:8088/api/agents/default/console/chat \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "console",
    "user_id": "neuromant",
    "session_id": "neuromant-api-session",
    "input": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Привет. Ответь одной короткой фразой: ты жив?"}
        ]
      }
    ]
  }'
```

## Example skill folder layout

### Minimal skill
```text
copaw-api-chat/
├── SKILL.md
└── references/
    ├── overview-auth-scoping.md
    ├── chats-console-sse.md
    ├── agents-models-skills-tools.md
    ├── workspace-mcp-cron.md
    └── practical-recipes.md
```

### Project-local knowledge next to skill
```text
project/
├── .agents/
│   └── skills/
│       └── copaw-api-chat/
│           ├── SKILL.md
│           └── references/
└── notes/
```

### Split between quick routing and deeper refs
```text
copaw-api-chat/
├── SKILL.md          # short router
└── references/       # detailed API notes
```

## Confirmed practical test
A direct local API test succeeded with this sequence:
- list agents → `default`
- create chat
- send message in that session context
- receive text answer from CoPaw
rames return the assistant response


path: references/workspace-mcp-cron.md
content: # Workspace / MCP / Cron

These API groups exist, but they are not the first place to start if the goal is simply to talk to CoPaw.

## /api/workspace
High-risk admin surface.
Use for:
- workspace export/import

Risk:
- can overwrite or leak workspace contents

## /api/mcp
Use for:
- managing MCP client config
- understanding integration boundaries around MCP

Important:
- this is config management, not the same thing as talking to CoPaw as a chat agent

## /api/cron
Use for:
- scheduled jobs
- cron inspection / control

Important:
- useful later for automation around CoPaw, not for the first chat integration step

## Rule of thumb
If the task is:
- "talk to CoPaw"
start with `chats-console-sse.md`

If the task is:
- "administer CoPaw"
then these APIs become relevant.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)