<!-- YAML Frontmatter -->
---
name: arcsmith-api
description: Automate, sync, and manipulate narrative graph structures and cast assets in the running ArcSmith editor via its background REST API. Trigger this skill whenever you need to fetch project states, programmatically update the canvas, manage sub-resources (characters, variables, environments, scenes, nodes, connections), or execute active editor actions (undo, redo, focus nodes, switch scenes).
---

# ArcSmith Editor API Integration Skill

Use this skill to interface with the local REST API server exposed by the running ArcSmith desktop Tauri application.

## 1. Server Metadata & Setup
- **Base URL:** http://127.0.0.1:14230
- **Authentication:** Zero-configuration (no keys or tokens required — binds strictly to loopback).
- **Schema Discovery:** GET /api/schema returns all endpoints at runtime.

## 2. CORS Policy
- GET / OPTIONS: Access-Control-Allow-Origin: * (read-only, safe to expose)
- POST / PATCH / DELETE: Access-Control-Allow-Origin: null (blocks cross-origin browser requests; curl/Python/Node.js unaffected)

## 3. API Endpoints

### Health
- **GET /health** — Returns {"status":"ok","version":"1.0.1","service":"ArcSmith"}
- **GET /api/schema** — Machine-readable endpoint listing

### Narrative Project
- **GET /api/project** — Fetch the full project JSON. Waits up to 2s for startup sync.
- **POST /api/project** — Replace the entire project state. Body: application/json.

### Sub-Resources CRUD
:resource = characters | environments | variables | scenes | nodes | connections
- **GET /api/:resource** — List all items (returns {} or [] if key absent, never 500).
- **POST /api/:resource** — Create/upsert item. ID auto-generated if omitted. Injects default fields.
- **GET /api/:resource/:id** — Fetch single item or 404.
- **PATCH /api/:resource/:id** — Shallow-merge partial fields onto existing item. Body: application/json.
- **DELETE /api/:resource/:id** — Remove item with full cascade cleanup.
  - Cannot delete the last scene (returns 409 Conflict).
  - Scenes: clears entryNodeId + resets activeSceneId to first remaining scene.

### Editor Action Commands
- **GET /api/actions** — Returns {"allowed_actions": [...]}
- **POST /api/actions** — Triggers an editor operation:
    - {"action": "undo"} -> Revert last change (Ctrl+Z)
    - {"action": "redo"} -> Re-apply last change (Ctrl+Y)
    - {"action": "new_project"} -> Reset to clean canvas
    - {"action": "select_node", "payload": {"nodeId": "id" | null}} -> Highlight node
    - {"action": "set_active_scene", "payload": {"sceneId": "id"}} -> Switch scene tab
  - Unknown action names return 400 with the allowed list.

## 4. Data Schemas (Sub-Resources)
- **Character:** {"id": string, "name": string, "portraits": string[], "customProperties"?: object}
- **Environment:** {"id": string, "name": string, "description": string, "imagePath"?: string, "customProperties"?: object}
- **Variable:** {"id": string, "name": string, "type": "bool"|"int"|"str", "value": any}
- **Scene:** {"id": string, "name": string, "color": string}
- **ArcNode:** {"id": string, "type": "dialogue"|"monologue"|"hub"|"condition"|"set"|"jump", "x": number, "y": number, "sceneId": string, "data": object}
  - type, x, y, sceneId are REQUIRED for POST — returns 422 if missing.
- **ArcConnection:** {"id": string, "fromNode": string, "fromSlot": string, "toNode": string, "toSlot": string}

## 5. HTTP Status Codes Used
- 200 OK — Success
- 400 Bad Request — Malformed JSON or bad field values
- 404 Not Found — Resource or ID not found
- 405 Method Not Allowed — Includes Allow header (RFC 7231)
- 409 Conflict — Cannot delete last scene
- 413 Content Too Large — Body exceeds 20 MB
- 415 Unsupported Media Type — Missing Content-Type: application/json
- 422 Unprocessable Entity — Valid JSON but missing required node fields
- 500 Internal Server Error — Mutex poisoned or serialisation failure
- 503 Service Unavailable — Too many concurrent connections (limit: 32)

curl http://localhost:14230/api/project

const res = await fetch('http://localhost:14230/api/project');
const project = await res.json();
console.log(project);

Invoke-RestMethod -Uri http://localhost:14230/api/project

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"title":"My Story","description":"","entryNodeId":null,"characters":{},"environments":{},"variables":{},"scenes":{},"nodes":{},"connections":[],"assets":[]}' \
  http://localhost:14230/api/project

const payload = {
  title: "My Story",
  description: "",
  entryNodeId: null,
  characters: {},
  environments: {},
  variables: {},
  scenes: {},
  nodes: {},
  connections: [],
  assets: []
};

const res = await fetch('http://localhost:14230/api/project', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload)
});

Invoke-RestMethod -Uri http://localhost:14230/api/project -Method Post -Body '{"title":"My Story","description":"","entryNodeId":null,"characters":{},"environments":{},"variables":{},"scenes":{},"nodes":{},"connections":[],"assets":[]}' -ContentType "application/json"

curl http://localhost:14230/api/characters

const res = await fetch('http://localhost:14230/api/characters');
const characters = await res.json();
console.log(characters);

Invoke-RestMethod -Uri http://localhost:14230/api/characters

curl http://localhost:14230/api/characters/18bc7557258d3cec

const res = await fetch('http://localhost:14230/api/characters/18bc7557258d3cec');
const character = await res.json();
console.log(character);

Invoke-RestMethod -Uri http://localhost:14230/api/characters/18bc7557258d3cec

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name":"Alistair","portraits":["pose1.png"]}' \
  http://localhost:14230/api/characters

const characterData = {
  name: "Alistair",
  portraits: ["pose1.png"]
};

const res = await fetch('http://localhost:14230/api/characters', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(characterData)
});

Invoke-RestMethod -Uri http://localhost:14230/api/characters -Method Post -Body '{"name":"Alistair","portraits":["pose1.png"]}' -ContentType "application/json"

curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"name":"Alistair Thorne"}' \
  http://localhost:14230/api/characters/18bc7557258d3cec

// Only updates the 'name' field — all other fields unchanged
const res = await fetch('http://localhost:14230/api/characters/18bc7557258d3cec', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: "Alistair Thorne" })
});
const updated = await res.json();

Invoke-RestMethod -Uri http://localhost:14230/api/characters/18bc7557258d3cec -Method Patch -Body '{"name":"Alistair Thorne"}' -ContentType "application/json"

curl -X DELETE http://localhost:14230/api/characters/18bc7557258d3cec

const res = await fetch('http://localhost:14230/api/characters/18bc7557258d3cec', {
  method: 'DELETE'
});

Invoke-RestMethod -Uri http://localhost:14230/api/characters/18bc7557258d3cec -Method Delete

{
  "allowed_actions": [
    "undo", "redo", "new_project", "select_node", "set_active_scene"
  ]
}

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"action":"undo"}' \
  http://localhost:14230/api/actions

const payload = {
  action: "select_node",
  payload: { nodeId: "18bc7557258d3cec" }
};

const res = await fetch('http://localhost:14230/api/actions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(payload)
});

Invoke-RestMethod -Uri http://localhost:14230/api/actions -Method Post -Body '{"action":"undo"}' -ContentType "application/json"

{
  "status": "error",
  "message": "Unknown action 'fly_away'. See allowed_actions.",
  "allowed_actions": ["undo", "redo", "new_project", "select_node", "set_active_scene"]
}

curl http://localhost:14230/api/schema

const res = await fetch('http://localhost:14230/api/schema');
const schema = await res.json();
console.log(schema.endpoints);

Invoke-RestMethod -Uri http://localhost:14230/api/schema