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

# Vayl HTTP API

Call Vayl's 32 tools over plain HTTP: one REST operation per tool, JSON in and out, Bearer auth.

`vayl-server` serves every Vayl tool as a REST operation: `POST /v1/tools/<name>` with the tool's arguments as a JSON object, returning `{"result": "..."}`. The same tools are available over MCP at `POST /mcp` for MCP clients and agent frameworks. Both paths run the same code, with the same authentication, capability checks, scoping and audit log.

## Quick start

Start a server and create an API key (see [Deploying vayl-server](https://vayl.gitbook.io/vayl-docs/documentation/guides/deploying-vayl-server)), then:

```bash
curl -s localhost:8080/v1/tools/remember \
  -H "Authorization: Bearer $VAYL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Acme Corp is on the Enterprise plan, account active.", "user_id": "cust_5521"}'
```

```json
{"result":"Stored: [ADD] plan = Enterprise; [ADD] account_status = active"}
```

A later fact replaces the old one, and an agent can check before it acts:

```bash
curl -s localhost:8080/v1/tools/remember -H "Authorization: Bearer $VAYL_KEY" -H "Content-Type: application/json" \
  -d '{"text": "Acme'\''s invoice bounced. Account suspended until payment clears.", "user_id": "cust_5521"}'
curl -s localhost:8080/v1/tools/check_before_act -H "Authorization: Bearer $VAYL_KEY" -H "Content-Type: application/json" \
  -d '{"subject": "account_status", "user_id": "cust_5521", "block_on_recent_change_days": 1}'
```

```json
{"result":"Stored: [ADD] acme_invoice_payment_status = bounced; [SUPERSEDE] account_status = suspended"}
{"result":"⛔ BLOCKED — do NOT act on 'account_status':\n  • recently changed 0.0d ago — may be unsettled"}
```

These are real responses from `vayl-server` with the support preset (`VAYL_SLOT_SCHEMA=preset:support`). `recall` answers are written by your model, so their wording varies.

## Endpoints

| Route                         | Auth                          | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /v1/tools/<name>`       | API key or OIDC token         | Run one tool. See the tool pages: [Memory](https://vayl.gitbook.io/vayl-docs/api-reference/tools/memory.md), [Safety and approval](https://vayl.gitbook.io/vayl-docs/api-reference/tools/safety-and-approval.md), [Accountability](https://vayl.gitbook.io/vayl-docs/api-reference/tools/accountability.md), [Compliance](https://vayl.gitbook.io/vayl-docs/api-reference/tools/compliance.md), [Administration](https://vayl.gitbook.io/vayl-docs/api-reference/tools/administration.md). |
| `GET /v1/tools`               | API key or OIDC token         | Every tool with its JSON Schema, the same as MCP `tools/list`.                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `POST /mcp`                   | API key or OIDC token         | MCP JSON-RPC: `initialize`, `tools/list`, `tools/call`. See [MCP endpoint](https://vayl.gitbook.io/vayl-docs/api-reference/mcp-endpoint.md).                                                                                                                                                                                                                                                                                                                                               |
| `GET /healthz`, `GET /readyz` | none                          | Liveness and readiness. See [Health probes](https://vayl.gitbook.io/vayl-docs/api-reference/health-probes.md).                                                                                                                                                                                                                                                                                                                                                                             |
| `GET /metrics`                | none, or `VAYL_METRICS_TOKEN` | Prometheus counters. See [Metrics](https://vayl.gitbook.io/vayl-docs/api-reference/metrics.md).                                                                                                                                                                                                                                                                                                                                                                                            |

## Authentication

Send `Authorization: Bearer <credential>` on every `/v1` and `/mcp` request:

* an API key (`vayl_sk_…`), created with the [`create_principal`](https://vayl.gitbook.io/vayl-docs/api-reference/tools/administration.md) tool and shown once; or
* an OIDC ID token, with an Enterprise license granting `sso`.

A key's role decides which tools it may call, and its `scopes` decide which `user_id`s it may touch. The server speaks plain HTTP, so terminate TLS at a reverse proxy or ingress.

## Status codes

| Code  | Meaning                                                                                                                | Body                                              |
| ----- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `200` | The tool ran. A tool that couldn't finish still answers `200`, with `Vayl couldn't complete that (ref …)` in `result`. | `{"result": "..."}`                               |
| `400` | The body isn't a JSON object.                                                                                          | `{"error": "..."}`                                |
| `401` | No credential, or one that isn't an active principal.                                                                  | `{"error": "unauthorized: ..."}`                  |
| `403` | The key's role lacks the tool's capability, or the `user_id` is outside its scopes. The denial is audited.             | `{"result": "Access denied: ..."}`                |
| `404` | No tool by that name. `GET /v1/tools` lists them.                                                                      | `{"error": "..."}`                                |
| `413` | The body is larger than `VAYL_MAX_BODY` (1 MiB by default).                                                            | `{"error": "request body too large"}`             |
| `422` | An argument is missing, unknown or the wrong type. `detail` names it.                                                  | `{"error": "invalid arguments", "detail": "..."}` |
| `429` | This client IP went over `VAYL_RATE_PER_MIN` (120 by default, per process).                                            | `{"error": "rate limit exceeded"}`                |

Every response carries an `X-Request-ID` header. Send your own (1 to 64 characters of `A-Z a-z 0-9 . _ : -`) to match proxy and Vayl logs, and quote it, with any `ref`, when you report a problem.

## REST or MCP?

Use REST from backend code, scripts and anything that isn't an MCP client: it's one HTTP request per call, with no JSON-RPC envelope or event stream. Use MCP for chat clients (Claude Code, Cursor) and agent frameworks, which discover the tools and let the model call them. The Python and TypeScript clients use MCP; see [Calling Vayl from code](https://vayl.gitbook.io/vayl-docs/documentation/getting-started/calling-vayl-from-code).

{% hint style="info" %}
This reference is generated from [`openapi/vayl-server.yaml`](https://github.com/ac12644/vayl/blob/main/openapi/vayl-server.yaml), which `openapi/generate.py` builds from the server's tool registry. The examples on the tool pages are real responses, captured by `openapi/capture_examples.py`. A test fails if the spec drifts from the code.
{% endhint %}

## List the tools

> Every tool with its title, description and JSON Schema for its arguments: the same list as MCP \`tools/list\`, sorted by name.

```json
{"openapi":"3.1.0","info":{"title":"Vayl HTTP API","version":"0.11.0"},"tags":[{"name":"Tools","description":"Discover the tools over REST."}],"servers":[{"url":"http://127.0.0.1:8080","description":"Default bind address (VAYL_HOST / VAYL_PORT). Put TLS in front for anything but local use."}],"security":[{"apiKey":[]},{"oidc":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"vayl_sk_…","description":"An API key created with the `create_principal` tool. Shown once; only its hash is stored."},"oidc":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"An OIDC ID token (RS256), verified against `VAYL_OIDC_JWKS_URL` with `iss`, `aud` and `exp`\nrequired. Needs an Enterprise license granting `sso` and `pip install \"vayl-mcp[sso]\"`.\n"}},"parameters":{"RequestId":{"name":"X-Request-ID","in":"header","required":false,"description":"Correlation ID. Reused if it is 1–64 characters of `A-Z a-z 0-9 . _ : -` (so proxy and Vayl\nlogs line up); otherwise replaced with a generated one. Echoed on the response and stamped on\nevery log line written while serving the request.\n","schema":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9._:-]{1,64}$"}}},"schemas":{"ToolList":{"type":"object","properties":{"tools":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":["string","null"]},"description":{"type":"string"},"input_schema":{"type":"object","description":"JSON Schema for the tool's arguments."}}}}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string","description":"For `422`, which argument is wrong and why."}}}},"responses":{"Unauthorized":{"description":"No credential, or one that doesn't resolve to an active principal.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/v1/tools":{"get":{"tags":["Tools"],"operationId":"listTools","summary":"List the tools","description":"Every tool with its title, description and JSON Schema for its arguments: the same list as MCP `tools/list`, sorted by name.","parameters":[{"$ref":"#/components/parameters/RequestId"}],"responses":{"200":{"description":"The tools.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
