How do I use the API?
Overview
The Aiceberg API provides a streamlined interface for real-time AI content analysis and risk detection. This single-endpoint API allows you to submit prompts and receive analysis results in one call, making it ideal for integration and testing.
Base URLs
Get base URL from customer success team during onboarding.
Authentication
All API requests require authentication using an API key in the Authorization header:
Authorization: YOUR_API_KEYEvent Analysis Endpoint
POST /eap/v1/eventDescription
Submit a prompt for real-time analysis and receive comprehensive risk assessment results. This endpoint processes your input through Aiceberg's Detection and Response platform and returns signal analysis, token counts, and system actions.
Headers
Content-Type
application/json
Yes
Authorization
YOUR_API_KEY
Yes
New or refreshed API keys may take up to 15 minutes to become active. If you receive authentication errors immediately after creation, please wait a few minutes and try again.
Request Body
Example request body:
Parameters
use_case_id
string
Conditional
Use case identifier that automatically resolves its configured profile. Required if profile_id is not provided. Prohibited if profile_id is provided. When provided, event_type is also required
profile_id
string
Conditional
The profile to use for analysis. Required if use_case_id is not provided. Prohibited if use_case_id is provided
input
string
Conditional
The prompt or content to be analyzed. Required unless output is provided with a valid event_id. For agt_tool events, the value must be a JSON-serialized string containing tool_name (string), tool_args (object), and tool_call_id (string) — a structured object will not be accepted.
output
string
Conditional
The LLM or agent response to be analyzed. Can be sent alone with a valid event_id to analyze a previously submitted input, or together with input in a single call
instructions
string
No
Additional instructions for the LLM or analysis process
event_type
string
No
Type of event being monitored at the agentic boundary (default: "user_llm"). Required when use_case_id is provided. See Event Types table for valid values.
log_group
string
No
Logging category ("monitoring", "sandbox")
event_id
string
No
Custom event identifier. If not provided, one will be assigned automatically. Required when sending an output-only request — capture the event_id from the input response and include it in the subsequent output call
session_id
string
No
Session identifier for grouping related events
session_start
boolean
No
Set to true on the first event in a new session. Only send on opening turn
forward_to_llm
boolean
No
Whether to forward the request to the configured LLM (default: true)
background
boolean
No
Process in background mode (default: false)
metadata
object
No
Additional metadata for the event
user_id
string
No
Use metadata field to pass user context {"user_id: USER_ID}
initiator
object
No
The entity that originated the request. Contains type (string), name (string|null), id (string|null), and metadata (object|null). Contains type (string), name (string|null), id (string|null), and metadata (object|null). If provided, metadata must be a valid dictionary — a plain string will return a 422 error.
sender
object
No
The entity sending the event at this specific boundary. Contains type (string), name (string|null), id (string|null), and metadata (object|null). Contains type (string), name (string|null), id (string|null), and metadata (object|null). If provided, metadata must be a valid dictionary — a plain string will return a 422 error.
receiver
object
No
The entity receiving the event at this specific boundary. Contains type (string), name (string|null), id (string|null), and metadata (object|null). Contains type (string), name (string|null), id (string|null), and metadata (object|null). If provided, metadata must be a valid dictionary — a plain string will return a 422 error.
session_end
boolean
No
Set to true on the final event of a session
session_status
string
Conditional
The outcome of the session. Required when session_end is true. Valid values: finished, blocked, model error, internal error.
Event Types
The event_type field specifies which agentic boundary is being monitored. Select the value that matches the interaction your AI system is performing:
user_llm
User --> LLM
A human or machine user submitting input to an AI agent or LLM. Default value
user_agt
User --> Agent
A human or machine user submitting input to an AI agent. Default value
agt_llm
Agent --> LLM
An AI agent submitting a prompt or context to an LLM for inference or completion
agt_tool
Agent --> Tool
An agent invoking an external, API, or function call. Pass tool call details as a JSON-serialized string in input with keys tool_name, tool_args, and tool_call_id. Pass the tool result as a JSON-serialized string in output with keys tool_name, tool_call_id, and tool_result
agt_mem
Agent --> Memory
An agent reading from or writing to a memory or context store
agt_agt
Agent --> Agent
An orchestrator agent delegating tasks to a sub-agent
agt_user
Agent --> User
A human or machine user receiving output from an AI agent
Learn more about event types here.
Response
Success Response (200 OK)
Response Fields
event_id
string
Unique identifier for this analysis event
event_type
string
Type of event ("user_llm")
status
string
Processing status ("finished", "processing", "failed")
created_at
number
Unix timestamp when the event was created
finished_at
number|null
Unix timestamp when processing completed
input
string
The original input prompt
output
string
Generated response if processed, or block message if rejected
session_id
string|null
Session identifier for tracking related events
profile_id
string
Profile used for analysis
profile_version
number
Version of the profile configuration
user_id
string
User identifier defaults to 'apikey' if not set. To set a custom value, pass inside the metadata object--top level is not accepted
log_group
string
Logging category ("monitoring", "sandbox")
input_signal_result
string
Overall risk assessment for input
output_signal_result
string|null
Overall risk assessment for output (null if no LLM response generated)
event_result
string
Final event classification (e.g., passed, flagged, rejected)
input_system_actions
array
Actions taken on input (e.g., "log", "modify", "block", "alert")
output_system_actions
array
Actions taken on output (e.g., "log", "alert")
input_token_count
number
Number of tokens in the input
output_token_count
number
Number of tokens in the output (0 if blocked)
initiator
string
Type values include user, agent, LLM
sender
object
Type values include user, agent, LLM
receiver
object
Type values include user, agent, LLM, memory, tool
Error Responses
New or refreshed API keys may take up to 15 minutes to become active. If you receive authentication errors immediately after creation, please wait a few minutes and try again.
Best Practices
Event Classification: Use the event_result field to determine appropriate handling:
passed: Process output normally
flagged: Process with additional monitoring
rejected: Handle as policy violation with explanation
Tool Event Formatting: For
agt_toolevents, theinputandoutputfields must be strings. Serialize tool call details as JSON:inputshould containtool_name,tool_args, andtool_call_id;outputmay containtool_name,tool_call_id, andtool_result.A structured object won't work here. Note that the tool inspector signal only returns results on inputs.Event Types: Always set event_type to match the actual agentic boundary being monitored. Using the correct type ensures the appropriate signal profile is applied and that sessions are grouped correctly in the AIceberg dashboard.
Signal Monitoring: Monitor both input_signal_result and output_signal_result for comprehensive risk assessment.
Session Management: Use a consistent session_id across all turns in a conversation or workflow. Set session_start: true only on the first event of each new session.
Input/Output Splitting: You can send input and output in a single request, or send them separately. If sending separately, capture the event_id from the input response and include it in the output-only request.
Token Tracking: Use token counts for usage monitoring and billing.
Audit Trail: Store event_id for correlation with Aiceberg's audit logs.
Profile Management: Ensure your profile_id is valid and properly configured for your use case.
Metadata Usage: Leverage the metadata field to store additional context for analysis and debugging.
Support
For API support, questions, or sample scripts email [email protected]
This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the privacy policy.
Last updated