# 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",
      "scope": "step",
      "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 '{
    "agent_id": "agent-123",
    "task_id": "task-abc",
    "scope": "step",
    "step_type": "step.model",
    "verb": "POST",
    "step_name": "chat_gpt-4o",
    "input": {"user_message": "Hello"},
    "output": {"response": "Hi there!"}
  }'
```

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kyvvu.com/integrations/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.