API Reference

The FORG Rule Engine REST API. Ingest signals, query sessions, and manage goals programmatically.

Base URL

https://forg.pro/engine/v1

All requests must use HTTPS. The Rule Engine is a Cloudflare Worker; the /engine/v1 path is proxied from the Next.js site for developer convenience.

Authentication

All endpoints require a valid license key passed as a Bearer token in the Authorization header:

Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c

License tokens use the format lic_<20hex>. Find yours in the dashboard under Settings → License. Missing or invalid tokens return 401 Unauthorized.

POST/signals

Ingest a behavioral signal from an adapter or custom integration.

Request body

{
  "type":       "post-tool",          // required — signal type
  "adapter":    "claude-code",        // required — adapter identifier
  "session_id": "sess_4f9a2e1b",     // required — session ID
  "metadata": {                       // optional — arbitrary key/value
    "model":    "claude-opus-4-5",
    "tokens_in":  1024,
    "tokens_out": 512,
    "cost_usd":   0.0042
  }
}

Valid signal types: user-prompt, post-tool, pre-compact, session-start, session-end, stop, hesitation, deletion, correction, session-pause, goal-drift, context-switch, tool-switch, token-milestone, refocus-ack, completion-verified, adapter-heartbeat.

Example

curl -X POST https://forg.pro/engine/v1/signals \
  -H "Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "post-tool",
    "adapter": "claude-code",
    "session_id": "sess_4f9a2e1b",
    "metadata": {
      "model": "claude-opus-4-5",
      "tokens_in": 1024,
      "tokens_out": 512,
      "cost_usd": 0.0042
    }
  }'

Response

{
  "ok": true,
  "signal_id": "sig_9e3a1f2b4c7d"
}

GET/sessions

List sessions for the authenticated user, newest first.

Query parameters

Example

curl "https://forg.pro/engine/v1/sessions?limit=50&before=2025-06-01T00:00:00Z" \
  -H "Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c"

Response

{
  "sessions": [
    {
      "id":         "sess_4f9a2e1b",
      "adapter":    "claude-code",
      "started_at": "2025-05-29T14:32:10Z",
      "ended_at":   "2025-05-29T15:14:43Z",
      "signals":    47,
      "tokens_in":  24601,
      "tokens_out": 12288,
      "cost_usd":   0.94
    }
    // ...
  ]
}

GET/sessions/:id

Retrieve a single session and its full signal list.

Example

curl "https://forg.pro/engine/v1/sessions/sess_4f9a2e1b" \
  -H "Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c"

Response

{
  "session": {
    "id":         "sess_4f9a2e1b",
    "adapter":    "claude-code",
    "started_at": "2025-05-29T14:32:10Z",
    "ended_at":   "2025-05-29T15:14:43Z",
    "signals":    47,
    "tokens_in":  24601,
    "tokens_out": 12288,
    "cost_usd":   0.94
  },
  "signals": [
    {
      "id":         "sig_9e3a1f2b4c7d",
      "type":       "post-tool",
      "timestamp":  "2025-05-29T14:33:02Z",
      "metadata": {
        "model":      "claude-opus-4-5",
        "tokens_in":  1024,
        "tokens_out": 512,
        "cost_usd":   0.0042
      }
    }
    // ...
  ]
}

GET/goals

List active goals for the authenticated user.

Example

curl "https://forg.pro/engine/v1/goals" \
  -H "Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c"

Response

{
  "goals": [
    {
      "id":          "goal_7c3a2e1b",
      "description": "Implement authentication flow",
      "status":      "active",
      "adapter":     "claude-code",
      "created_at":  "2025-05-29T14:32:10Z"
    }
  ]
}

POST/goals

Create a new goal. The rule engine uses active goals to detect goal drift signals.

Request body

{
  "description": "Implement authentication flow",   // required
  "adapter":     "claude-code"                       // optional
}

Example

curl -X POST https://forg.pro/engine/v1/goals \
  -H "Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c" \
  -H "Content-Type: application/json" \
  -d '{"description": "Implement authentication flow", "adapter": "claude-code"}'

Response

{
  "goal": {
    "id":          "goal_7c3a2e1b",
    "description": "Implement authentication flow",
    "status":      "active",
    "adapter":     "claude-code",
    "created_at":  "2025-05-29T14:32:10Z"
  }
}

PATCH/goals/:id

Update a goal's status or description.

Request body

{
  "status":      "completed",              // "active" | "completed" | "abandoned"
  "description": "Updated goal text"       // optional
}

Example

curl -X PATCH https://forg.pro/engine/v1/goals/goal_7c3a2e1b \
  -H "Authorization: Bearer lic_a3f9e2c1b84d7f6e0a2c" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}'

Response

{
  "goal": {
    "id":          "goal_7c3a2e1b",
    "description": "Implement authentication flow",
    "status":      "completed",
    "adapter":     "claude-code",
    "created_at":  "2025-05-29T14:32:10Z",
    "updated_at":  "2025-05-29T16:00:00Z"
  }
}

Errors

All errors return a consistent JSON body:

{
  "error":      "Invalid signal type: unknown-type",
  "code":       "invalid_signal_type",
  "status":     400,
  "request_id": "req_9f3e2a1b"
}