How do I use the API?

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 URL

https://api.prod1.aiceberg.ai

Authentication

All API requests require authentication using an API key in the Authorization header:

Authorization: YOUR_API_KEY

Event Analysis Endpoint

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	Recommended
Authorization	YOUR_API_KEY	Yes

Request Body

The request body supports the following parameters:

{
  "profile_id": "string",
  "profile_version": 0,
  "input": "string", 
  "output": "string",
  "instructions": "string",
  "event_type": "user_llm",
  "log_group": "monitoring",
  "event_id": "string",
  "session_id": "string",
  "forward_to_llm": true,
  "background": false,
  "metadata": {
    "additionalProp1": {}
}

Parameters

Parameter	Type	Required	Description
profile_id	string	Yes	The unique identifier for your Aiceberg profile configuration
profile_version	number	No	Version of the profile configuration to use (defaults to latest)
input	string	Yes	The prompt or content to be analyzed
instructions	string	No	Additional instructions for the LLM or analysis process
event_type	string	No	Type of event (default: "user_llm")
log_group	string	No	Logging category ("monitoring", "sandbox")
event_id	string	No	Custom event identifier for tracking
session_id	string	No	Session identifier for grouping related events
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

Response

Success Response (200 OK)

{
  "event_id": "string",
  "event_type": "string", 
  "status": "string",
  "created_at": 1752267389.178874,
  "finished_at": null,
  "input": "string",
  "output": "string", 
  "session_id": "string",
  "profile_id": "string",
  "profile_version": 2,
  "user_id": "string",
  "log_group": "string",
  "input_signal_result": "string",
  "output_signal_result": "string",
  "event_result": "string",
  "input_system_actions": ["log"],
  "output_system_actions": ["log"],
  "input_token_count": 5,
  "output_token_count": 7
}

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	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
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
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)

Error Responses

400 Bad Request

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

401 Unauthorized

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

404 Not Found

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

500 Internal Server Error

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

Best Practices

• Error Handling: Always check the status field and handle potential errors gracefully
• Event Classification: Use the event_result field to determine appropriate handling:
  • passed: Process output normally
  • flagged: Process with additional monitoring
  • blocked: Handle as policy violation with explanation
• Signal Monitoring: Monitor both input_signal_result and output_signal_result for comprehensive risk assessment
• 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
• Session Management: Use consistent session_id values to group related interactions
• Metadata Usage: Leverage the metadata field to store additional context for analysis and debugging

Support

For API support, questions, or sample scripts email support@aiceberg.ai