How do I use the API?

Developer docs link

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:

Example header

Authorization: YOUR_API_KEY

Event Analysis Endpoint

HTTP

POST /eap/v1/event

Description

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

Header	Value	Required
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:

Request body (application/json)

{
  "use_case_id": "string", //use either use_case_id or profile_id, not both
  "event_type": "user_llm",
  "input": "string",
  "output": "string",
  "instructions": "string",
  "log_group": "monitoring",
  "event_id": "string",
  "session_id": "string",
  "session_start": false,
  "session_end": false,
  "session_status": "finished",
  "forward_to_llm": true,
  "background": false,
  "metadata": {
    "user_id": "your-user-identifier"
  },
  "initiator": {
    "type": "user",
    "name": "string",
    "id": "string",
    "metadata": null
  },
  "sender": {
    "type": "agent",
    "name": "string",
    "id": "string",
    "metadata": null
  },
  "receiver": {
    "type": "llm",
    "name": "string",
    "id": "string",
    "metadata": null
  }
}

Parameters

Parameter	Type	Required	Description
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:

Value	Boundary	Description
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)

Success response (200 OK)

  "event_id": "01KPRTC2JSBAG55023GV2VT9YP",
  "event_type": "user_llm",
  "status": "finished",
  "created_at": 1776801942.1051722,
  "finished_at": 1776801942.4290268,
  "input": "What is the capital of France?",
  "output": "The capital of France is Paris.",
  "session_id": "stag-session-1776801942",
  "profile_id": "01KPED5JJA7TA8YT6JQ4D43D1A",
  "profile_version": 2,
  "user_id": "apikey",
  "log_group": "monitoring",
  "input_signal_result": "none",
  "output_signal_result": "none",
  "event_result": "passed",
  "input_system_actions": ["log"],
  "output_system_actions": ["log"],
  "input_token_count": 6,
  "output_token_count": 6,
  "initiator": {
    "type": "user",
    "name": "[email protected]",
    "id": "[email protected]",
    "metadata": null
  },
  "sender": {
    "type": "agent",
    "name": "my_agent",
    "id": "my_agent_id",
    "metadata": null
  },
  "receiver": {
    "type": "llm",
    "name": "my_llm",
    "id": "my_llm_id",
    "metadata": {
      "env": "production",
      "version": "1.0"
    }
  }
}

Response Fields

Field	Type	Description
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.

400 Bad Request

400 Bad Request

{
  "error": "Bad Request",
  "message": "Missing required field: profile_id"
}

401 Unauthorized

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

404 Not Found

404 Not Found

{
  "error": "Not Found",
  "message": "Profile not found"
}

422 Unprocessable Entity

422 Unprocessable Entity

{
  "detail": [
    {
      "type": "dict_type",
      "loc": ["body", "sender", "metadata"],
      "msg": "Input should be a valid dictionary",
      "input": "test_agent_metadata"
    }
  ]
}

500 Internal Server Error

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

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_tool events, the input and output fields must be strings. Serialize tool call details as JSON: input should contain tool_name, tool_args, and tool_call_id; output may contain tool_name, tool_call_id, and tool_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.