Logging events to OTAS Brain

Every API call your agent makes should be logged to Brain as a BackendEvent. Brain is the OTAS service that stores, indexes, and serves analytics for all observed activity. There are two ways to get events into Brain: the server-side SDK middleware (which captures in-domain requests automatically when your agent attaches a session token) and the direct agent log endpoint (which your agent calls manually after making any external API call). Both paths produce the same BackendEvent record — they differ only in the authentication mechanism and who initiates the log call.

Logging modes

Via backend SDK key (in-domain)
Via agent key (out-of-domain)

This path is used by your project’s server-side middleware to automatically capture events for any request your agent makes within the project domain. Your agent does not call Brain directly — it simply attaches the session token to the in-domain request, and the middleware handles the rest.Endpoint: POST http://localhost:8002/api/v1/backend/log/sdk/Required headers:

Header	Value
`X-OTAS-SDK-KEY`	The project’s backend SDK key
`X-OTAS-AGENT-SESSION-TOKEN`	The session JWT obtained from UASAM
`Content-Type`	`application/json`

Example (server middleware):

curl -X POST http://localhost:8002/api/v1/backend/log/sdk/ \
  -H "X-OTAS-SDK-KEY: sdk_your_backend_key_here" \
  -H "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/some-resource",
    "method": "GET",
    "status_code": 200,
    "latency_ms": 45.2
  }'

Successful response:

{
  "status": 1,
  "status_description": "event_captured",
  "response": {}
}

The SDK log response does not include an event_id. Use the agent log endpoint if you need to track individual event IDs.

This path is used directly by your agent to log any external API call — one made outside the project domain. Your agent must call this endpoint immediately after completing the external request, with the measured latency and full request/response details.Endpoint: POST http://localhost:8002/api/v1/backend/log/agent/Required headers:

Header	Value
`X-OTAS-AGENT-KEY`	Your agent key (`agent_<prefix>_<secret>`)
`X-OTAS-AGENT-SESSION-TOKEN`	The session JWT obtained from UASAM
`Content-Type`	`application/json`

Brain verifies that the agent_id encoded in the session JWT matches the agent associated with the provided agent key. Mismatches are rejected with a 403 session_agent_mismatch error.Example:

curl -X POST http://localhost:8002/api/v1/backend/log/agent/ \
  -H "X-OTAS-AGENT-KEY: agent_abc123_yoursecrethere" \
  -H "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "/api/v1/the-external-path",
    "method": "POST",
    "status_code": 200,
    "latency_ms": 123.45
  }'

Successful response:

{
  "status": 1,
  "status_description": "event_captured",
  "response": {
    "event_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

The agent log response includes an event_id UUID you can use to reference the specific event later.

Required fields

Every event log request — regardless of which endpoint you use — must include these five fields. Requests missing any of them will be rejected with a 400 missing_required_fields error that lists which fields are absent.

project_id

string

required

UUID of the OTAS project this event belongs to. Must match the project associated with the SDK key or agent key you are using.

path

string

required

The API path that was called, e.g., /api/v1/some-resource. For external calls, use the path portion of the external URL.

method

string

required

The HTTP method used: GET, POST, PUT, PATCH, DELETE, etc.

status_code

integer

required

The HTTP status code returned by the API, e.g., 200, 201, 404, 500.

latency_ms

float

required

The measured round-trip time in milliseconds. This value is used directly in p50/p95/p99 latency analytics — measure it accurately.

Optional fields

These fields are not required but provide richer observability data and enable more detailed filtering in the OTAS dashboard.

Field	Type	Description
`request_size_bytes`	integer	Size of the request body in bytes
`response_size_bytes`	integer	Size of the response body in bytes
`request_headers`	string	JSON-encoded request headers (e.g., `"{\"Content-Type\": \"application/json\"}"`)
`request_body`	string	JSON-encoded request body
`query_params`	string	Query string from the request URL
`post_data`	string	Form-encoded POST data, if applicable
`response_headers`	string	JSON-encoded response headers
`response_body`	string	JSON-encoded response body
`request_content_type`	string	MIME type of the request (e.g., `application/json`)
`response_content_type`	string	MIME type of the response
`custom_properties`	object	Arbitrary JSON object for agent-defined metadata
`error`	string	Error message if the call failed. A non-empty value marks the event as an error in analytics
`metadata`	object	Arbitrary JSON object for additional structured context

Full example request body

The following example shows all fields populated — use this as a reference for out-of-domain log calls:

{
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "/api/v1/the-external-path",
  "method": "POST",
  "status_code": 200,
  "latency_ms": 123.45,
  "request_size_bytes": 512,
  "response_size_bytes": 1024,
  "request_headers": "{\"Content-Type\": \"application/json\"}",
  "request_body": "{\"your\": \"request body\"}",
  "query_params": "",
  "post_data": "",
  "response_headers": "{\"Content-Type\": \"application/json\"}",
  "response_body": "{\"your\": \"response body\"}",
  "request_content_type": "application/json",
  "response_content_type": "application/json",
  "custom_properties": {},
  "error": "",
  "metadata": {}
}

Error responses

Status	`status_description`	Cause
`401`	`missing_sdk_key` / `missing_agent_key`	The required authentication header is absent
`401`	`invalid_sdk_key` / `invalid_or_expired_agent_key`	The key does not exist, is expired, or has been revoked
`401`	`missing_agent_session_token`	The `X-OTAS-AGENT-SESSION-TOKEN` header is absent
`401`	`invalid_or_expired_token`	The session JWT is malformed, expired, or invalid
`403`	`session_agent_mismatch`	The agent ID in the JWT does not match the agent key (agent endpoint only)
`400`	`missing_required_fields`	One or more of the five required fields are missing from the request body
`400`	`invalid_json`	The request body is not valid JSON

Best practices

Measure latency_ms using a timer that starts immediately before you send the request and stops as soon as you receive the full response. This value drives p50, p95, and p99 latency analytics — inaccurate measurements will skew your percentile charts.

Set error to a non-empty string whenever the call fails or returns an error status code. This is what Brain uses to count errors in the error-rate analytics view.
Use custom_properties to attach agent-specific context (e.g., which LLM model was used, which tool was invoked) that is not captured by the standard fields.
Log out-of-domain events immediately after each call, not in a batch at the end of the task. Batching risks losing events if the process exits unexpectedly.

Get Started

Core Concepts

Agent Integration

Analytics & Dashboard

Deployment

Logging events to OTAS Brain

Logging modes

Required fields

Optional fields

Full example request body

Error responses

Best practices

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agent Integration

Analytics & Dashboard

Deployment

​Logging modes

​Required fields

​Optional fields

​Full example request body

​Error responses

​Best practices

Build docs developers (and LLMs) love

Logging modes

Required fields

Optional fields

Full example request body

Error responses

Best practices