> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# Hooks Server API Overview

> API reference for the Guardrails hooks server, nemoguardrails hooks-server: the agent hook endpoints and the health checks.

The Guardrails hooks server (`nemoguardrails hooks-server`) checks coding agents' tool calls before they run.
It is a separate server from the [Guardrails API Server](/nemo/guardrails/v0.25.0/run-guardrailed-inference/using-fastapi-server), with its own endpoints.
For running it and connecting agents, refer to [Use the Guardrails Hooks Server](/nemo/guardrails/v0.25.0/run-guardrailed-inference/using-hooks-server).

## Base URL

The default base URL is:

```text
http://localhost:8100
```

The server listens on `127.0.0.1:8100` by default. Set `--host` and `--port` to change it.

## Authentication

The hooks server has no authentication.
Keep it on `127.0.0.1`, or on a private network that restricts who can reach the port.

## Endpoints

The server exposes the following endpoints:

| Endpoint                                                                | Description                                                              |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| [`POST /v1/hooks/claude-code`](/nemo/guardrails/v0.25.0/reference/hooks-server-api/claude-code) | Check a tool call from a Claude Code `PreToolUse` hook                   |
| [`POST /v1/hooks/codex`](/nemo/guardrails/v0.25.0/reference/hooks-server-api/codex)             | Check a tool call from a Codex `PreToolUse` hook                         |
| [`POST /v1/hooks/nemo-relay`](/nemo/guardrails/v0.25.0/reference/hooks-server-api/nemo-relay)   | Check a tool call from a NeMo Relay tool conditional-execution guardrail |
| [`GET /v1/health`](/nemo/guardrails/v0.25.0/reference/hooks-server-api/get-health)              | Liveness health check                                                    |
| [`GET /healthz`](/nemo/guardrails/v0.25.0/reference/hooks-server-api/get-healthz)               | Liveness health check (alias)                                            |

Every other path returns `404`, and the server serves no OpenAPI document or docs pages.

Each hook endpoint applies the same configuration: the path selects only the agent's request and response format.
The server reads the request body as JSON whatever its `Content-Type` header says.

## Outcomes

A hook endpoint answers each check with one of three outcomes:

| Outcome | Status                 | Body                                                                   |
| ------- | ---------------------- | ---------------------------------------------------------------------- |
| Allow   | `200`                  | `{}` for Claude Code and Codex; `{"decision": "allow"}` for NeMo Relay |
| Deny    | `200`                  | The agent's deny shape, with the reason                                |
| Error   | `422`, `500`, or `503` | The OpenAI error envelope                                              |

For error codes and when they occur, refer to [Hooks Server Results and Errors](/nemo/guardrails/v0.25.0/run-guardrailed-inference/using-hooks-server/results-and-errors#errors).