Runtime Integration API

Use the Runtime Integration API when a hook, gateway, collector, or fleet script needs to send data into AgentKeeper or request a policy decision. These endpoints are intentionally POST-heavy...

Use the Runtime Integration API when a hook, gateway, collector, or fleet script needs to send data into AgentKeeper or request a policy decision. These endpoints are intentionally POST-heavy because the caller is reporting observations or asking for enforcement before a tool runs.

For data export, SIEM sync, warehouse ingestion, or settings automation, use API Reference to check the current customer API boundary.

Base URL

https://www.agentkeeper.dev

export AGENTKEEPER_API_URL="https://www.agentkeeper.dev"
export AGENTKEEPER_API_KEY="ak_live_..."

Authentication

Runtime endpoints use organization-scoped API keys from Settings > Access > API keys.

curl -fsS "$AGENTKEEPER_API_URL/api/v1/shield/policy" \
  -H "Authorization: Bearer $AGENTKEEPER_API_KEY"

Runtime keys are write-oriented. They can evaluate policy, submit events, report workstation posture, and send telemetry. They cannot read dashboard history, list users, change billing, or administer the organization.

Endpoint Index

Runtime Evaluation

Method	Path	Use
`POST`	`/api/v1/evaluate?tool=<tool>`	Unified policy evaluation for supported agent adapters
`POST`	`/api/v1/audit?tool=<tool>`	Unified post-tool audit ingestion
`POST`	`/api/v1/claude-code/evaluate`	Claude Code `UserPromptSubmit` and `PreToolUse` evaluation
`POST`	`/api/v1/claude-code/audit`	Claude Code `PostToolUse` audit
`POST`	`/api/v1/claude-code/checkin`	Claude Code `SessionStart` check-in
`GET`	`/api/v1/claude-code/health`	API-key connectivity check

Supported values for evaluation and audit tool:

Value	Surface
`claude-code`	Claude Code-compatible payloads
`claude-chat`	Claude Desktop Chat MCP Gateway activity
`cowork`	Claude Cowork Local Agent Mode activity
`cursor`	Cursor
`windsurf`	Windsurf
`copilot`	VS Code Copilot
`codex`	Codex
`gemini`	Gemini CLI
`antigravity`	Google Antigravity
`grok`	Grok

Events And Policy

Method	Path	Use
`GET`	`/api/v1/shield/policy`	Fetch baseline Runtime Shield policy for the API key's organization
`POST`	`/api/v1/shield/events`	Ingest a batch of Runtime Shield events
`POST`	`/api/v1/shield/heartbeat`	Mark Runtime Shield active on a workstation
`POST`	`/api/v1/events`	Ingest lifecycle events such as install or uninstall

Workstation Posture

Method	Path	Use
`POST`	`/api/v1/scans`	Upload workstation posture, gateway posture, or Cowork posture scan results

MCP

Method	Path	Use
`POST`	`/api/v1/mcp/evaluate`	Evaluate an MCP server/tool call before execution
`POST`	`/api/v1/mcp/events`	Ingest MCP activity events
`POST`	`/api/v1/mcp/sync`	Sync MCP Gateway inventory

OTLP

Method	Path	Use
`POST`	`/api/v1/otlp/v1/logs`	Ingest Claude Code, Claude Agent SDK, and Cowork logs as evidence
`GET`	`/api/v1/otlp/health`	Check OTLP ingestion health
`GET`	`/api/v1/otlp/setup-health`	Validate telemetry setup

When setting Claude Code environment variables, use the base endpoint https://www.agentkeeper.dev/api/v1/otlp. When a product UI asks for an exact logs endpoint, use https://www.agentkeeper.dev/api/v1/otlp/v1/logs.

Evaluate A Tool Call

POST /api/v1/evaluate?tool=cursor
Authorization: Bearer ak_live_...
Content-Type: application/json

curl -fsS "$AGENTKEEPER_API_URL/api/v1/evaluate?tool=cursor" \
  -H "Authorization: Bearer $AGENTKEEPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hook_event_name": "PreToolUse",
    "tool_name": "Bash",
    "tool_input": {
      "command": "cat ~/.aws/credentials"
    },
    "hostname": "dev-laptop-01",
    "session_id": "session-123",
    "cwd": "/Users/alex/work/app"
  }'

Common request fields:

Field	Type	Required	Notes
`tool_name`	string	Yes	Normalized tool name such as `Bash`, `Read`, `Write`, or `mcp__server__tool`
`tool_input`	object	Yes	Tool arguments used for policy evaluation
`hook_event_name`	string	Recommended	Hook phase, usually `PreToolUse`
`hostname`	string	Recommended	Workstation identity fallback
`machine_id`	string	Recommended for fleet installs	Stable workstation identity
`session_id`	string	Recommended	Groups events into investigations
`cwd`	string	Recommended	Working directory for path and repository context
`user_hint`	string	Optional	Email or username for attribution and group policy

Claude-compatible deny response:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by AgentKeeper org policy"
  }
}

Generic adapter response:

{
  "decision": "deny",
  "reason": "Blocked by AgentKeeper org policy"
}

Evaluation endpoints may return 200 even when an action is blocked. Agent hook runtimes often treat non-200 responses as hook failures instead of policy decisions. Read the response body for the verdict.

Audit A Completed Tool Call

POST /api/v1/audit?tool=cursor
Authorization: Bearer ak_live_...
Content-Type: application/json

Audit endpoints record completed actions and output-risk findings. They do not block the completed action.

curl -fsS "$AGENTKEEPER_API_URL/api/v1/audit?tool=cursor" \
  -H "Authorization: Bearer $AGENTKEEPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "Read",
    "tool_input": {
      "file_path": "/Users/alex/work/app/package.json"
    },
    "tool_output": "{ "name": "app" }",
    "hostname": "dev-laptop-01",
    "session_id": "session-123",
    "cwd": "/Users/alex/work/app"
  }'

Successful audit response:

{}

Upload Shield Events

POST /api/v1/shield/events
Authorization: Bearer ak_live_...
Content-Type: application/json

Use this endpoint when a collector has already made a policy decision and needs to send events in batches.

{
  "events": [
    {
      "hostname": "dev-laptop-01",
      "detection_layer": "claude_code",
      "verdict": "blocked",
      "severity": "high",
      "security_level": "strict",
      "input_hash": "sha256-or-client-hash",
      "session_id": "session-123",
      "tool_name": "Bash",
      "enforcement_reason": "Blocked by AgentKeeper org policy",
      "context": {
        "tool_input": {
          "command": "cat ~/.aws/credentials"
        }
      }
    }
  ]
}

Limits:

Limit	Value
Events per batch	100
Stored context size	Bounded and truncated server-side

Upload A Workstation Scan

POST /api/v1/scans
Authorization: Bearer ak_live_...
Content-Type: application/json

{
  "hostname": "dev-laptop-01",
  "machine_id": "hardware-or-mdm-stable-id",
  "platform": "darwin",
  "os_version": "macOS 15.5",
  "agent_version": "agentkeeper-gateway/0.3.2",
  "source": "gateway",
  "score": 92,
  "grade": "A",
  "checks": [
    {
      "status": "passed",
      "check_name": "Claude Code hooks installed",
      "category": "runtime",
      "severity": "medium"
    }
  ],
  "raw_report": {
    "collector": "agentkeeper-gateway"
  }
}

Required fields:

Field	Type	Notes
`hostname`	string	Workstation display name
`checks`	array	Posture checks and evidence
`raw_report`	object or string	Collector evidence

MCP Evaluation And Events

MCP calls can reach AgentKeeper through native agent hooks as tool names like mcp__notion__notion-create-pages, or through MCP-specific endpoints.

Use /api/v1/mcp/evaluate when the caller needs a pre-execution decision for an MCP server/tool call.

Use /api/v1/mcp/events when the caller is reporting observed MCP activity after the call.

Use /api/v1/mcp/sync when a gateway or collector is reporting inventory.

Security Notes

API keys are scoped to one organization.
Raw API keys are shown only at creation time.
Server-side storage uses hashed keys.
Runtime API keys do not grant dashboard read or admin access.
All API calls should use HTTPS.
Use separate API keys for MDM, GitHub repo hooks, Cowork, and gateway installs when independent rotation matters.

Was this page helpful?