POST /api/v1/backend/log/agent/

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

{
  "status": 0,
  "status_description": "session_agent_mismatch"
}

{
  "status": 0,
  "status_description": "missing_required_fields",
  "missing_fields": ["path", "method"]
}

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

{
  "status": 0,
  "status_description": "session_agent_mismatch"
}

{
  "status": 0,
  "status_description": "missing_required_fields",
  "missing_fields": ["path", "method"]
}

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

string

required

The agent’s API key. Used to identify and authenticate the agent via UASAM.

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

string

required

UUID of the project this event belongs to.

string

required

The external API path that was called (e.g. /api/v1/the-external-path).

string

required

HTTP method used for the external request (e.g. GET, POST, PUT, DELETE).

number

required

HTTP status code returned by the external API.

number

required

Actual measured round-trip latency of the external request in milliseconds.

Optional fields

number

Size of the request payload in bytes.

number

Size of the response payload in bytes.

string

Serialized request headers sent to the external API.

string

Raw or serialized request body sent to the external API.

string

Query string or serialized query parameters.

string

Form post data, if applicable.

string

Serialized response headers received from the external API.

string

Raw or serialized response body received from the external API.

string

Content-Type of the request (e.g. application/json).

string

Content-Type of the response.

object

Arbitrary JSON object for attaching user-defined metadata to the event.

string

Error message or identifier if the external request failed. Leave empty on success.

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.

number

required

1 on success, 0 on failure.

string

required

event_captured on success.

object

required

Show properties

string

required

UUID of the newly created BackendEvent record.

Errors

HTTP	`status_description`	Meaning
401	`missing_agent_key`	`X-OTAS-AGENT-KEY` header was not provided.
401	`invalid_or_expired_agent_key`	The agent key was not recognised, is inactive, or the UASAM call failed.
401	`missing_agent_session_token`	`X-OTAS-AGENT-SESSION-TOKEN` header was not provided.
401	`invalid_or_expired_token`	The session JWT is malformed, expired, or has invalid claims.
403	`session_agent_mismatch`	The JWT’s `agent_id` does not match the agent identified by the agent key.
400	`missing_required_fields`	One or more required body fields are absent. See `missing_fields`.
500	`event_capture_failed`	An 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"
  }
}

{
  "status": 0,
  "status_description": "session_agent_mismatch"
}

{
  "status": 0,
  "status_description": "missing_required_fields",
  "missing_fields": ["path", "method"]
}

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

POST /api/v1/backend/log/agent/

Request

Body

Response

Errors

​Request

​Body

​Response

​Errors

Request

Body

Response

Errors