---
title: "Record a tool call audit entry"
method: POST
path: "/api/v1/audit/tool-call"
tags: ["Audit"]
---

# Record a tool call audit entry

`POST /api/v1/audit/tool-call`

## Request

- Base URL: `https://orchestrator.getaxonflow.com`
- URL: `https://orchestrator.getaxonflow.com/api/v1/audit/tool-call`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/docs/api/v1/audit/tool-call/post.ts> (a function with typed inputs; its response is checked against the schema)

Records a non-LLM tool call (API calls, webhooks, MCP tool executions by external
orchestrators) in the AxonFlow audit trail. Only `tool_name` is required; all other
fields are optional.

## Headers

- `X-Tenant-ID` string, required
- `X-Axonflow-Proxy-Auth` string, required
- `Idempotency-Key` string

## Request body

- AuditToolCallRequest
  - `tool_name` string, required: Name of the tool that was called
  - `caller_name` string: Which client/integration made this call (e.g. claude_code, codex, cursor, openclaw). Replaces tool_type (#2912), which was misnamed for this purpose — every real caller used it to identify itself, not to describe a property of the tool.
  - `tool_type` string: Deprecated — use caller_name instead. Accepted as a legacy input fallback when caller_name is not supplied.
  - `input` object: Input data sent to the tool
  - `output` object: Output data returned by the tool
  - `workflow_id` string: Associated workflow ID
  - `step_id` string: Associated workflow step ID
  - `user_id` string: User who triggered the tool call
  - `duration_ms` integer: Duration of the tool call in milliseconds
  - `policies_applied` string[]: List of policy names applied during the tool call
  - `success` boolean: Whether the tool call succeeded
  - `error_message` string: Error message if the tool call failed

## Response `201`

Tool call audit recorded

- AuditToolCallResponse
  - `audit_id` string: Unique identifier for the audit entry
  - `status` 'recorded': Recording status
  - `timestamp` string, date-time: When the audit entry was recorded

## Other responses

- `400`: Bad request (missing tool_name, invalid body, or missing X-Tenant-ID)
- `401`: Missing or invalid Basic auth credentials
- `403`: Client ID does not match tenant scope, or request not routed through Agent gateway

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)