> For the complete documentation index, see [llms.txt](https://docs.kyvvu.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kyvvu.com/integrations/rest-api.md).

# REST API / Local Engine

**What you'll learn:** How to integrate non-Python agents with Kyvvu using the local HTTP server (`kyvvu serve`).

***

## `kyvvu serve` (local engine)

For agents written in JavaScript, Go, Rust, or any language, `kyvvu serve` runs the engine as a local HTTP server. Your agent makes HTTP calls to evaluate steps — same engine, same sub-millisecond policies, no Python needed in your agent code.

### Start the server

```bash
pip install kyvvu
kyvvu serve --host 127.0.0.1 --port 8080 --agent-key my-agent
```

The server needs API credentials to fetch policies. Provide them via flags or environment variables:

```bash
export KV_API_URL=https://platform.kyvvu.com
export KV_API_KEY=KvKey-...
export KV_AGENT_KEY=my-agent
kyvvu serve
```

### Endpoints

| Method | Path              | Purpose                                        |
| ------ | ----------------- | ---------------------------------------------- |
| `GET`  | `/health`         | Liveness probe — returns policy status.        |
| `POST` | `/evaluate`       | Preflight evaluation of an intended behaviour. |
| `POST` | `/record`         | Record a completed step into task history.     |
| `POST` | `/end_task`       | Close a task — evict history and flush logs.   |
| `POST` | `/register_agent` | Evaluate agent-registration policies.          |

### Health check

```bash
curl http://127.0.0.1:8080/health
```

```json
{
  "policy_count": 8,
  "last_fetch_at": "2026-04-29T10:00:00+00:00",
  "last_fetch_succeeded": true,
  "instance_id": "worker-3-a8f92",
  "ttl_remaining_seconds": 280.5
}
```

### Evaluate a step

```bash
curl -X POST http://127.0.0.1:8080/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "intended": {
      "agent_id": "agent-123",
      "task_id": "task-abc",
      "step_type": "step.model",
      "verb": "POST",
      "step_name": "chat_gpt-4o",
      "input": {"user_message": "Hello"}
    },
    "context": {
      "agent_id": "agent-123",
      "task_id": "task-abc",
      "environment": "production",
      "risk_classification": "limited"
    }
  }'
```

Response:

```json
{
  "action": "allow",
  "risk_score": 0.0,
  "policies": [
    {
      "policy_id": 1,
      "name": "pii_in_request",
      "severity": "critical",
      "violated": false,
      "violation_details": null
    }
  ],
  "blocked": false
}
```

When a policy blocks, `blocked` is `true` and `action` is `"block"`. The server always returns HTTP 200 for policy decisions — read the `blocked` field to decide whether to proceed.

### Record a completed step

```bash
curl -X POST http://127.0.0.1:8080/record \
  -H "Content-Type: application/json" \
  -d '{
    "step": {
      "agent_id": "agent-123",
      "task_id": "task-abc",
      "step_type": "step.model",
      "verb": "POST",
      "step_name": "chat_gpt-4o",
      "input": {"user_message": "Hello"},
      "output": {"response": "Hi there!"}
    }
  }'
```

> `/record` nests the Behavior under a `step` key. `/evaluate` nests it under `intended` and requires a sibling `context` object.

> **Behavior objects are strict.** A Behavior in a request body accepts only the fields the schema defines: `agent_id`, `task_id`, `timestamp`, `step`, `step_type`, `verb`, `step_name`, `input`, `output`, `properties`, and `meta`. Any other key returns HTTP 422 identifying the field the server rejected.

Response: `{"step": 1, "task_id": "task-abc"}`

### End a task

```bash
curl -X POST http://127.0.0.1:8080/end_task \
  -H "Content-Type: application/json" \
  -d '{"task_id": "task-abc"}'
```

Response: `{"status": "ok", "task_id": "task-abc"}`

### Integration pattern

The typical flow for a non-Python agent:

```
1. POST /evaluate  → check if step is allowed
2. If blocked=false: execute the step
3. POST /record    → record the completed step with output
4. Repeat for each step
5. POST /end_task  → flush logs and clean up
```

***

## Next steps

* [kyvvu serve](/cli-reference/serve.md) — CLI reference for the serve command
* [Configuration Reference](/deployment/configuration.md) — all environment variables
* [Architecture](/core-concepts/architecture.md) — why in-process evaluation is preferred