Skip to navigation

Hooks Server API Overview

View as MarkdownOpen in Claude

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, with its own endpoints. For running it and connecting agents, refer to Use the Guardrails Hooks Server.

Base URL

The default base URL is:

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:

EndpointDescription
POST /v1/hooks/claude-codeCheck a tool call from a Claude Code PreToolUse hook
POST /v1/hooks/codexCheck a tool call from a Codex PreToolUse hook
POST /v1/hooks/nemo-relayCheck a tool call from a NeMo Relay tool conditional-execution guardrail
GET /v1/healthLiveness health check
GET /healthzLiveness 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:

OutcomeStatusBody
Allow200{} for Claude Code and Codex; {"decision": "allow"} for NeMo Relay
Deny200The agent’s deny shape, with the reason
Error422, 500, or 503The OpenAI error envelope

For error codes and when they occur, refer to Hooks Server Results and Errors.