Skip to main content
Agents use this endpoint to log calls to external APIs — APIs outside the project domain that the OTAS middleware does not intercept automatically. After making an external request, send its details here so OTAS can attribute the event to the correct session and agent. Brain verifies that the session JWT’s agent_id claim matches the agent identified by the provided agent key, ensuring a session cannot be used to log events on behalf of a different agent.
You must call the session creation endpoint first to obtain an X-OTAS-AGENT-SESSION-TOKEN before logging events. The session token is bound to a single process — never reuse it across separate runs.

​
Request

​
X-OTAS-AGENT-KEY
string
required
The agent’s API key. Used to identify and authenticate the agent via UASAM.
​
X-OTAS-AGENT-SESSION-TOKEN
string
required
Session JWT obtained from the session creation endpoint. Must have been issued for the same agent as the agent key.

​
Body

Required fields
​
project_id
string
required
UUID of the project this event belongs to.
​
path
string
required
The external API path that was called (e.g. /api/v1/the-external-path).
​
method
string
required
HTTP method used for the external request (e.g. GET, POST, PUT, DELETE).
​
status_code
number
required
HTTP status code returned by the external API.
​
latency_ms
number
required
Actual measured round-trip latency of the external request in milliseconds.
Optional fields
​
request_size_bytes
number
Size of the request payload in bytes.
​
response_size_bytes
number
Size of the response payload in bytes.
​
request_headers
string
Serialized request headers sent to the external API.
​
request_body
string
Raw or serialized request body sent to the external API.
​
query_params
string
Query string or serialized query parameters.
​
post_data
string
Form post data, if applicable.
​
response_headers
string
Serialized response headers received from the external API.
​
response_body
string
Raw or serialized response body received from the external API.
​
request_content_type
string
Content-Type of the request (e.g. application/json).
​
response_content_type
string
Content-Type of the response.
​
custom_properties
object
Arbitrary JSON object for attaching user-defined metadata to the event.
​
error
string
Error message or identifier if the external request failed. Leave empty on success.
​
metadata
object
Additional JSON metadata for internal or debugging purposes.

​
Response

On success the endpoint returns HTTP 201 and includes an event_id in the response object. You can use this ID to retrieve the event later via the session events endpoint.
​
status
number
required
1 on success, 0 on failure.
​
status_description
string
required
event_captured on success.
​
response
object
required

​
Errors

HTTPstatus_descriptionMeaning
401missing_agent_keyX-OTAS-AGENT-KEY header was not provided.
401invalid_or_expired_agent_keyThe agent key was not recognised, is inactive, or the UASAM call failed.
401missing_agent_session_tokenX-OTAS-AGENT-SESSION-TOKEN header was not provided.
401invalid_or_expired_tokenThe session JWT is malformed, expired, or has invalid claims.
403session_agent_mismatchThe JWT’s agent_id does not match the agent identified by the agent key.
400missing_required_fieldsOne or more required body fields are absent. See missing_fields.
500event_capture_failedAn unexpected server-side error occurred while saving the event.
session_agent_mismatch (403) means the session token you are using was issued for a different agent than the key you provided. Always create a new session with the same agent key you intend to log with.
curl --request POST \
  --url http://localhost:8002/api/v1/backend/log/agent/ \
  --header "X-OTAS-AGENT-KEY: agk_live_xyz789" \
  --header "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
    "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": {}
  }'

{
  "status": 1,
  "status_description": "event_captured",
  "response": {
    "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us