Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.adrian.secureagentics.ai/llms.txt

Use this file to discover all available pages before exploring further.

Events represent individual actions or observations produced by your AI agents — prompts sent, completions received, tool calls made, and errors encountered. Sending events to Secureagentics enables real-time policy evaluation, anomaly detection, and audit trail generation.

​
Send an event

POST /v1/agents/{id}/events Sends a single activity event for the specified agent. Secureagentics evaluates the event against all applicable policies and returns the result synchronously.

​
Path parameters

​
id
string
required
The ID of the agent sending the event, prefixed with agt_.

​
Request body

​
type
string
required
The event type. One of: prompt, completion, tool_call, error, custom.
​
payload
object
required
Event-specific data. The structure of this object depends on the event type. For example, a prompt event might include the input text, while a tool_call event might include the tool name and arguments.
​
trace_id
string
A correlation ID you provide for linking related events across a single request or conversation thread. If omitted, the event is not correlated with other events.
​
timestamp
string
ISO 8601 timestamp indicating when the event occurred. Defaults to the server’s current time if omitted.

​
Response fields

​
id
string
required
Unique event identifier, prefixed with evt_.
​
agent_id
string
required
The ID of the agent that produced the event.
​
type
string
required
The event type.
​
payload
object
required
The event payload as submitted.
​
trace_id
string
The correlation ID for this event, if provided.
​
timestamp
string
required
ISO 8601 timestamp of when the event occurred.
​
policy_result
object
required
The outcome of policy evaluation for this event.
curl --request POST \
  --url https://api.secureagentics.ai/v1/agents/agt_01j9xkz2m3n4p5q6r7s8t9u0/events \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "type": "prompt",
    "payload": {
      "input": "Summarize the following customer record...",
      "model": "gpt-4o"
    },
    "trace_id": "trace_abc123",
    "timestamp": "2026-05-04T10:30:00Z"
  }'

​
List events for an agent

GET /v1/agents/{id}/events Returns a paginated list of events produced by the specified agent. Use the from and to parameters to query events within a specific time window.

​
Path parameters

​
id
string
required
The agent ID, prefixed with agt_.

​
Query parameters

​
limit
integer
default:"50"
Maximum number of events to return per page. Accepted range: 1–500.
​
offset
integer
default:"0"
Number of events to skip before returning results. Use for pagination.
​
type
string
Filter events by type. One of: prompt, completion, tool_call, error, custom.
​
from
string
ISO 8601 timestamp. Return only events at or after this time.
​
to
string
ISO 8601 timestamp. Return only events at or before this time.

​
Response fields

​
items
object[]
required
Array of event objects matching the query. Each object has the same structure as the response from Send an event.
​
total
integer
required
Total number of events matching the applied filters, regardless of pagination.
curl --request GET \
  --url "https://api.secureagentics.ai/v1/agents/agt_01j9xkz2m3n4p5q6r7s8t9u0/events?type=prompt&from=2026-05-01T00:00:00Z&limit=50" \
  --header "Authorization: Bearer YOUR_API_KEY"

​
Send events in batch

POST /v1/agents/{id}/events/batch Sends multiple events for the specified agent in a single request. Each event is evaluated against applicable policies independently. The maximum batch size is 100 events per request.
Use batch ingestion to minimize API call overhead when your agent produces high volumes of events. This is especially useful for logging completion and tool_call events at the end of a processing pipeline.

​
Path parameters

​
id
string
required
The agent ID, prefixed with agt_.

​
Request body

​
events
object[]
required
Array of event objects to send. Maximum of 100 events per request. Each object accepts the same fields as the single-event endpoint: type, payload, trace_id, and timestamp.

​
Response fields

​
results
object[]
required
Array of event result objects in the same order as the submitted events. Each object has the same structure as the response from Send an event.
​
total
integer
required
Number of events successfully processed.
curl --request POST \
  --url https://api.secureagentics.ai/v1/agents/agt_01j9xkz2m3n4p5q6r7s8t9u0/events/batch \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "events": [
      {
        "type": "prompt",
        "payload": { "input": "What is the account balance for user 42?" },
        "trace_id": "trace_xyz789"
      },
      {
        "type": "completion",
        "payload": { "output": "The account balance is $1,200." },
        "trace_id": "trace_xyz789"
      }
    ]
  }'