# How do I use the API?

#### [Developer docs link](https://developers.test1.aiceberg.ai/)

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

{% code title="Example header" %}

```http
Authorization: YOUR_API_KEY
```

{% endcode %}

Event Analysis Endpoint

{% code title="HTTP" %}

```http
POST /eap/v1/event
```

{% endcode %}

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

{% hint style="info" %}
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.
{% endhint %}

### Request Body

Example request body:

{% code title="Request body (application/json)" %}

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

{% endcode %}

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

<table><thead><tr><th width="115.7578125">Value</th><th width="200.71484375">Boundary</th><th>Description</th></tr></thead><tbody><tr><td>user_llm</td><td>User --> LLM</td><td>A human or machine user submitting input to an AI agent or LLM. Default value</td></tr><tr><td>user_agt</td><td>User --> Agent</td><td>A human or machine user submitting input to an AI agent. Default value</td></tr><tr><td>agt_llm</td><td>Agent --> LLM</td><td>An AI agent submitting a prompt or context to an LLM for inference or completion</td></tr><tr><td>agt_tool</td><td>Agent --> Tool</td><td>An agent invoking an external, API, or function call. Pass tool call details as a JSON-serialized string in <code>input</code> with keys <code>tool_name</code>, <code>tool_args</code>, and <code>tool_call_id</code>. Pass the tool result as a JSON-serialized string in <code>output</code> with keys <code>tool_name</code>, <code>tool_call_id</code>, and <code>tool_result</code></td></tr><tr><td>agt_mem</td><td>Agent --> Memory</td><td>An agent reading from or writing to a memory or context store</td></tr><tr><td>agt_agt</td><td>Agent --> Agent</td><td>An orchestrator agent delegating tasks to a sub-agent</td></tr><tr><td>agt_user</td><td>Agent --> User</td><td>A human or machine user receiving output from an AI agent</td></tr></tbody></table>

[Learn more about event types here](https://docs.aiceberg.ai/monitoring/what-is-the-monitoring-page/what-are-events-and-how-are-they-monitored).&#x20;

### Response

Success Response (200 OK)

{% code title="Success response (200 OK)" %}

```json
  "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": "user@example.com",
    "id": "user@example.com",
    "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"
    }
  }
}
```

{% endcode %}

### Response Fields

<table><thead><tr><th>Field</th><th width="216" align="right">Type</th><th>Description</th></tr></thead><tbody><tr><td>event_id</td><td align="right">string</td><td>Unique identifier for this analysis event</td></tr><tr><td>event_type</td><td align="right">string</td><td>Type of event ("user_llm")</td></tr><tr><td>status</td><td align="right">string</td><td>Processing status ("finished", "processing", "failed")</td></tr><tr><td>created_at</td><td align="right">number</td><td>Unix timestamp when the event was created</td></tr><tr><td>finished_at</td><td align="right">number|null</td><td>Unix timestamp when processing completed</td></tr><tr><td>input</td><td align="right">string</td><td>The original input prompt</td></tr><tr><td>output</td><td align="right">string</td><td>Generated response if processed, or block message if rejected</td></tr><tr><td>session_id</td><td align="right">string|null</td><td>Session identifier for tracking related events</td></tr><tr><td>profile_id</td><td align="right">string</td><td>Profile used for analysis</td></tr><tr><td>profile_version</td><td align="right">number</td><td>Version of the profile configuration</td></tr><tr><td>user_id</td><td align="right">string</td><td>User identifier defaults to 'apikey' if not set. To set a custom value, pass inside the metadata object--top level is not accepted</td></tr><tr><td>log_group</td><td align="right">string</td><td>Logging category ("monitoring", "sandbox")</td></tr><tr><td>input_signal_result</td><td align="right">string</td><td>Overall risk assessment for input</td></tr><tr><td>output_signal_result</td><td align="right">string|null</td><td>Overall risk assessment for output (null if no LLM response generated)</td></tr><tr><td>event_result</td><td align="right">string</td><td>Final event classification (e.g., passed, flagged, rejected)</td></tr><tr><td>input_system_actions</td><td align="right">array</td><td>Actions taken on input (e.g., "log", "modify", "block", "alert")</td></tr><tr><td>output_system_actions</td><td align="right">array</td><td>Actions taken on output (e.g., "log", "alert")</td></tr><tr><td>input_token_count</td><td align="right">number</td><td>Number of tokens in the input</td></tr><tr><td>output_token_count</td><td align="right">number</td><td>Number of tokens in the output (0 if blocked)</td></tr><tr><td>initiator</td><td align="right">string</td><td>Type values include user, agent, LLM</td></tr><tr><td>sender</td><td align="right">object</td><td>Type values include user, agent, LLM</td></tr><tr><td>receiver</td><td align="right">object</td><td>Type values include user, agent, LLM, memory, tool</td></tr></tbody></table>

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

<details>

<summary>400 Bad Request</summary>

{% code title="400 Bad Request" %}

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

{% endcode %}

</details>

<details>

<summary>401 Unauthorized</summary>

{% code title="401 Unauthorized" %}

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

{% endcode %}

</details>

<details>

<summary>404 Not Found</summary>

{% code title="404 Not Found" %}

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

{% endcode %}

</details>

<details>

<summary>422 Unprocessable Entity</summary>

{% code title="422 Unprocessable Entity" %}

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

{% endcode %}

</details>

<details>

<summary>500 Internal Server Error</summary>

{% code title="500 Internal Server Error" %}

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

{% endcode %}

</details>

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 Formattin&#x67;**:** 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.&#x20;
* 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 <support@aiceberg.ai>

This site uses cookies to deliver its service and to analyze traffic. By browsing this site, you accept the [privacy policy](https://aiceberg.ai/privacy-policy).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aiceberg.ai/developers/api-usage/how-do-i-use-the-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.