---
name: goclaw-api-integration
description: Full GoClaw REST API reference for interacting with agents — chat completions, direct Knowledge Graph access, Memory search, and agent management. Plus nginx CSP fix for Knowledge Graph rendering.
version: 1.0.0
author: Lokki
tags: [goclaw, little-fox, api, knowledge-graph, memory, nginx, csp]
---

# GoClaw REST API Integration

GoClaw provides an OpenAI-compatible REST API (not just WebSocket) for interacting with agents, their Knowledge Graphs, and Memory directly.

## Connection

**Base URL:** `https://goclaw.valentinnews.sailor.bar` (or `http://127.0.0.1:18790` from the server)

**Headers required on all requests:**
```
Authorization: Bearer <agent-or-gateway-token>
X-GoClaw-User-Id: valentin
Content-Type: application/json
```

## Chat with an Agent (OpenAI-compatible)

```
POST /v1/chat/completions
```

```bash
curl -X POST https://goclaw.valentinnews.sailor.bar/v1/chat/completions \
  -H "Authorization: Bearer goclaw_b335f0749a29a92d4b927814d6ef62c2" \
  -H "X-GoClaw-User-Id: valentin" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "goclaw:fox-spirit",
    "messages": [{"role": "user", "content": "запомни: новый клиент Иванов, Lipari 41, 15-22 июля"}]
  }'
```

**Model format:** `goclaw:<agent-slug>` (e.g., `goclaw:fox-spirit`)

**Commands** (send in `content`):
- `запомни: [факт]` — save to knowledge graph
- `найди в графе: [запрос]` — search the graph
- `свяжи: X с Y как [отношение]` — add a relation
- `что знаешь о [тема]?` — retrieve from graph
- Any free text — agent understands naturally

**Response time:** 5–30 seconds (not instant).

## Agent UUID Discovery

Agent slug (`fox-spirit`) works for chat, but most direct API endpoints require UUID.

```
GET /v1/agents
```

```bash
curl -s https://goclaw.valentinnews.sailor.bar/v1/agents \
  -H "Authorization: Bearer goclaw_b335f0749a29a92d4b927814d6ef62c2" \
  -H "X-GoClaw-User-Id: valentin"
```

Returns list with UUIDs. Example for Fox Spirit:
```
019e7882-c61e-7485-ad85-d2d68892b93c
```

## Direct Knowledge Graph Access

### List Entities

```
GET /v1/agents/{UUID}/kg/entities?limit=50
```

```bash
curl -s "https://goclaw.valentinnews.sailor.bar/v1/agents/019e7882-c61e-7485-ad85-d2d68892b93c/kg/entities?limit=50" \
  -H "Authorization: Bearer goclaw_b335f0749a29a92d4b927814d6ef62c2" \
  -H "X-GoClaw-User-Id: valentin"
```

Response fields: `id`, `name`, `entity_type`, `description`, `confidence`, `external_id`, `created_at`, `updated_at`.

### Traverse Graph (find relations)

```
POST /v1/agents/{UUID}/kg/traverse
```

```bash
curl -s https://goclaw.valentinnews.sailor.bar/v1/agents/019e7882-c61e-7485-ad85-d2d68892b93c/kg/traverse \
  -H "Authorization: Bearer goclaw_b335f0749a29a92d4b927814d6ef62c2" \
  -H "X-GoClaw-User-Id: valentin" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "<entity-uuid>", "depth": 2}'
```

Returns connected entities with relation type in `via` field (e.g., `~manages`, `uses`, `~belongs_to`, `located_in`, `~works_on`, `~part_of`, `~references`).

## Direct Memory Access

### Search Memory

```
POST /v1/agents/{UUID}/memory/search
```

```bash
curl -s https://goclaw.valentinnews.sailor.bar/v1/agents/019e7882-c61e-7485-ad85-d2d68892b93c/memory/search \
  -H "Authorization: Bearer goclaw_b335f0749a29a92d4b927814d6ef62c2" \
  -H "X-GoClaw-User-Id: valentin" \
  -H "Content-Type: application/json" \
  -d '{"query": "Atlantic Sail", "limit": 5}'
```

## Nginx CSP Fix for Knowledge Graph (Sigma.js)

GoClaw uses Sigma.js with Web Workers (blob: URLs) to render the Knowledge Graph. If the graph doesn't render and the browser console shows:
```
Refused to create a worker from 'blob:...' because it violates Content Security Policy
```

The server's CSP meta-tag is missing `worker-src 'self' blob:`. Fix in nginx:

```nginx
sub_filter '<meta http-equiv="Content-Security-Policy"' '<meta data-removed="csp"';
sub_filter '<meta http-equiv="content-security-policy"' '<meta data-removed="csp"';
sub_filter '</head>' '<meta http-equiv="Content-Security-Policy" content="default-src \'self\'; script-src \'self\' \'unsafe-inline\' \'unsafe-eval\' blob:; worker-src \'self\' blob:; connect-src \'self\' https: wss:; img-src \'self\' data: blob:; style-src \'self\' \'unsafe-inline\'; font-src \'self\' data:;"></head>';
sub_filter_once off;
sub_filter_types text/html;

# Disable upstream gzip so sub_filter works on raw HTML
proxy_set_header Accept-Encoding "";
```

Then reload nginx:
```bash
nginx -t && systemctl reload nginx
```

After fix, hard refresh browser (Ctrl+F5 / Cmd+Shift+R) to clear cache.

## Token Types

GoClaw has two types of tokens:
- **Gateway token** (e.g., `goclaw_gw_token_2026`): For UI pairing/authentication in the browser dashboard. Used with User ID via the Pairing flow. Does NOT work for REST API.
- **Agent token** (e.g., `goclaw_b335f...`): For REST API calls. Used in `Authorization: Bearer` header. This is the token for API access.

## Agent Config (from /v1/agents)

Fox Spirit agent configuration:
- Model: `deepseek/deepseek-v4-flash` (via OpenRouter)
- Context window: 200,000 tokens
- Max tool iterations: 30
- Agent type: `predefined`, is_default: `true`
- Status: `active`
- Workspace: `/app/workspace/fox-spirit` (restricted)
- Memory: enabled (document memory: chunk 1000, overlap 200; episodic memory enabled)

## Pitfalls

- `/api/*` endpoints documented in guides may not exist — use `/v1/*` instead
- Slug-based agent IDs (e.g., `fox-spirit`) work for `/v1/chat/completions` and `GET /v1/agents/fox-spirit`, but **KG and Memory endpoints require UUID**
- **Traverse requires `entity_id`** — calling without it returns `"entity_id is required"`. First get entities via `GET /v1/agents/{UUID}/kg/entities`, then use the entity UUID in traverse
- `X-GoClaw-User-Id` header is mandatory — without it you get 400
- Memory search may return empty initially if nothing has been stored yet
- Traverse requires `entity_id` parameter — plain text queries don't work, use the UUID from entities list
