POST /api/v1/backend/log/sdk/

curl --request POST \
  --url http://localhost:8002/api/v1/backend/log/sdk/ \
  --header "X-OTAS-SDK-KEY: sdk_live_abc123" \
  --header "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
    "path": "/api/v1/users/",
    "method": "GET",
    "status_code": 200,
    "latency_ms": 87.4,
    "request_size_bytes": 0,
    "response_size_bytes": 1024,
    "request_headers": "{\"Accept\": \"application/json\"}",
    "request_body": "",
    "query_params": "page=1&limit=20",
    "post_data": "",
    "response_headers": "{\"Content-Type\": \"application/json\"}",
    "response_body": "{\"users\": [...]}",
    "request_content_type": "application/json",
    "response_content_type": "application/json",
    "custom_properties": {},
    "error": "",
    "metadata": {}
  }'

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

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

{
  "status": 0,
  "status_description": "missing_required_fields",
  "missing_fields": ["latency_ms", "status_code"]
}

curl --request POST \
  --url http://localhost:8002/api/v1/backend/log/sdk/ \
  --header "X-OTAS-SDK-KEY: sdk_live_abc123" \
  --header "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
    "path": "/api/v1/users/",
    "method": "GET",
    "status_code": 200,
    "latency_ms": 87.4,
    "request_size_bytes": 0,
    "response_size_bytes": 1024,
    "request_headers": "{\"Accept\": \"application/json\"}",
    "request_body": "",
    "query_params": "page=1&limit=20",
    "post_data": "",
    "response_headers": "{\"Content-Type\": \"application/json\"}",
    "response_body": "{\"users\": [...]}",
    "request_content_type": "application/json",
    "response_content_type": "application/json",
    "custom_properties": {},
    "error": "",
    "metadata": {}
  }'

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

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

{
  "status": 0,
  "status_description": "missing_required_fields",
  "missing_fields": ["latency_ms", "status_code"]
}

This endpoint is called by server-side middleware that intercepts in-domain requests made by agents. The SDK key identifies the project by calling UASAM to verify ownership, and the session token — a short-lived JWT issued at session creation — scopes the recorded event to a specific agent session. You do not call this endpoint directly from agent code; it is invoked automatically by the OTAS middleware installed in your backend framework.

Request

string

required

Backend SDK key for the project. Verified against UASAM before the event is stored.

string

required

Session JWT obtained from the session creation endpoint. Carries agent_session_id and agent_id claims.

Body

Required fields

string

required

UUID of the project this event belongs to.

string

required

The API path that was called (e.g. /api/v1/users/).

string

required

HTTP method of the request (e.g. GET, POST, PUT, DELETE).

number

required

HTTP response status code returned by the upstream service.

number

required

Round-trip latency of the 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 (e.g. a JSON-encoded string of key-value pairs).

string

Raw or serialized request body.

string

Query string or serialized query parameters.

string

Form post data, if applicable.

string

Serialized response headers.

string

Raw or serialized response body.

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 request resulted in an error. Leave empty on success.

object

Additional JSON metadata for internal or debugging purposes.

Response

On success the endpoint returns HTTP 201 with an empty response object. Unlike the agent log endpoint, no event_id is returned here — the SDK log path does not expose the created record’s identifier.

number

required

1 on success, 0 on failure.

string

required

event_captured on success.

object

required

Empty object {}. No event ID is included.

Errors

HTTP	`status_description`	Meaning
401	`missing_sdk_key`	`X-OTAS-SDK-KEY` header was not provided.
401	`invalid_sdk_key`	The SDK key was not recognised or is inactive.
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.
400	`invalid_json`	The request body could not be parsed as JSON.
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.

When status_description is missing_required_fields, the response also includes a missing_fields array listing each absent field name.

curl --request POST \
  --url http://localhost:8002/api/v1/backend/log/sdk/ \
  --header "X-OTAS-SDK-KEY: sdk_live_abc123" \
  --header "X-OTAS-AGENT-SESSION-TOKEN: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  --header "Content-Type: application/json" \
  --data '{
    "project_id": "3f6e2b10-8c1a-4d55-b9d4-0a2e3c7f1234",
    "path": "/api/v1/users/",
    "method": "GET",
    "status_code": 200,
    "latency_ms": 87.4,
    "request_size_bytes": 0,
    "response_size_bytes": 1024,
    "request_headers": "{\"Accept\": \"application/json\"}",
    "request_body": "",
    "query_params": "page=1&limit=20",
    "post_data": "",
    "response_headers": "{\"Content-Type\": \"application/json\"}",
    "response_body": "{\"users\": [...]}",
    "request_content_type": "application/json",
    "response_content_type": "application/json",
    "custom_properties": {},
    "error": "",
    "metadata": {}
  }'

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

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

{
  "status": 0,
  "status_description": "missing_required_fields",
  "missing_fields": ["latency_ms", "status_code"]
}

UASAM — Users & Auth

UASAM — Projects & Keys

UASAM — Agents

Brain — Event Capture

Brain — Analytics

POST /api/v1/backend/log/sdk/

Request

Body

Response

Errors

​Request

​Body

​Response

​Errors

Request

Body

Response

Errors