---
title: How do I use the API?
description: new api
---

[Skip to content](https://help.aiceberg.ai/documentation/how-do-i-use-the-api#main-content)

English - United States

Show submenu for translations

[Support portal](https://44100605.hs-sites.com/tickets-view?hsLang=en-us)

[![Aiceberg logo - Dark](https://help.aiceberg.ai/hubfs/Aiceberg%20logo%20-%20Dark.svg)](https://aiceberg.ai/)

Open main navigation

Close main navigation

- English - United States
  
  Show submenu for translations
- [Support portal](https://44100605.hs-sites.com/tickets-view)
- [Contact us](mailto:support@aiceberg.ai)

[Contact us](mailto:support@aiceberg.ai)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [Aiceberg Documentation](https://help.aiceberg.ai/documentation?hsLang=en-us)
2. [Getting Started](https://help.aiceberg.ai/documentation/getting-started?hsLang=en-us)

# 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 URLs

```
Production - https://api.prod1.aiceberg.ai
```

```
Staging - https://api.stag1.aiceberg.ai
```

#### Authentication

All API requests require authentication using an [API key](https://44100605.hs-sites.com/documentation/how-do-i-get-an-api-key?hsLang=en-us) in the Authorization header:

```
Authorization: YOUR_API_KEY
```

#### Event Analysis Endpoint

```
/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

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

```
{  "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](mailto:support@aiceberg.ai)

- [Getting Started](https://help.aiceberg.ai/documentation/getting-started?hsLang=en-us)
- [Signals](https://help.aiceberg.ai/documentation/signals?hsLang=en-us)
- [Inventory](https://help.aiceberg.ai/documentation/inventory?hsLang=en-us)
- [Monitoring](https://help.aiceberg.ai/documentation/monitoring?hsLang=en-us)
- [Tools](https://help.aiceberg.ai/documentation/tools?hsLang=en-us)
- [Release Notes](https://help.aiceberg.ai/documentation/release-notes?hsLang=en-us)

[![Aiceberg logo - light](https://help.aiceberg.ai/hs-fs/hubfs/Aiceberg%20logo%20-%20light.png?width=200&height=58&name=Aiceberg%20logo%20-%20light.png "Aiceberg logo - light")](https://help.aiceberg.ai/?hsLang=en-us)

[Privacy Policy](https://aiceberg.ai/privacy-policy)

<https://www.linkedin.com/company/aiceberg/> <https://twitter.com/aicebergai/> <https://www.youtube.com/@Aiceberg_AI> <https://podcasts.apple.com/us/podcast/how-hard-can-it-be/id1834147503> [mailto:support@aiceberg.ai](mailto:support@aiceberg.ai)

Copyright © 2025