For the complete documentation index, see llms.txt. This page is also available as Markdown.

Hooks

Check Policy

post

Evaluate a submitted policy against submitted evidence.

Authenticated with either an API key or the master key (the router-level gate), like POST /api/v1/usage/external-events: this identifies who sent the request, not whether its evidence is true. blocked is set when a required gate's outcome is not pass/not_applicable (an unresolved gate never counts as a pass).

The actual parse-and-evaluate work is otari_agent.domain.check.run_policy_check, shared with otari hook's own local evaluation: this route's own job is authentication, translating that function's tri-state request fields into its own typed ones, and turning PolicyCheckError into a 422.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

A policy body plus the evidence to check it against, both caller-supplied.

command_scopestring · enumOptional

What commands covers: call for the single tool call about to run, session for every command the session has run so far.

Default: callPossible values:
commandsstring[] · max: 10000 · nullableOptional

Shell commands the caller observed run or is about to run.

path_sourcestring · enum · nullableOptional

Which moment paths was read at, matching the runs values a path gate declares. Only three of the six runs values are legal here, because only those three are moments a path can be read at: pre_tool_use.edit_target for a write tool's own target before it runs, pre_tool_use.read_target for a read tool's, and stop.working_tree for git status once the turn is over. Required whenever paths is non-empty, and rejected with a 422 if omitted or set to any other value: either would resolve every path gate not_applicable, which loses enforcement without reporting anything. An empty paths needs no source.

Possible values:
pathsstring[] · max: 10000 · nullableOptional

Repo-relative paths this moment of the session puts in scope: what git status --porcelain reports, or the single target a tool call is about to write or read. path_source says which.

policy_yamlstring · min: 1 · max: 262144Required
Responses
200

Successful Response

application/json
blockedbooleanRequired
policy_idstringRequired
provenancestringOptionalDefault: client_reported
schema_versionstringRequired
post/api/v1/hooks/check
POST /api/v1/hooks/check HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 258

{
  "check_results": [
    {
      "detail": "",
      "gate_id": "text",
      "outcome": "pass"
    }
  ],
  "command_scope": "call",
  "commands": [
    "text"
  ],
  "judge_results": [
    {
      "gate_id": "text",
      "outcome": "pass",
      "reasoning": ""
    }
  ],
  "path_source": "pre_tool_use.edit_target",
  "paths": [
    "text"
  ],
  "policy_yaml": "text"
}
{
  "blocked": true,
  "policy_id": "text",
  "provenance": "client_reported",
  "results": [
    {
      "detail": "text",
      "enforcement": "text",
      "gate_id": "text",
      "message": "text",
      "outcome": "text"
    }
  ],
  "schema_version": "text"
}

Record Guardrail Definition

post

Keep one version of an agent guardrail, so the gate spans that name it can say what each gate is for.

otari hook sends this once per version, the first time it reports a check against it. The fingerprint is recomputed from the gates, and one that does not match the one sent is refused, so a version cannot be stored under another's name. Sending a version again changes nothing. A workspace keeps at most 1,000 versions, and a new one past that is refused with a 409. It is stored in the API key's workspace, beside that key's traces, and takes the same key a trace export does: a budget-exempt API key, never the master key.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body
digeststringRequiredPattern: ^[0-9a-f]{64}$
Responses
200

Successful Response

application/json
digeststringRequired
post/api/v1/hooks/guardrails
POST /api/v1/hooks/guardrails HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 162

{
  "digest": "text",
  "gates": [
    {
      "enforcement": "required",
      "gate_id": "text",
      "gate_type": "command",
      "message": "text",
      "origin": "repo",
      "runs": [
        "pre_tool_use.edit_target"
      ]
    }
  ]
}
{
  "digest": "text"
}

Last updated

Was this helpful?