Endpoint
POST /v1/guard/{api-id}/analyze
Authorization: Bearer {api-key}
Content-Type: application/json
Top-level fields
| Field | Type | Required | Description |
|---|
messages | array | Yes | OpenAI-format messages. The last user message is what gets analyzed; earlier messages are context. |
opticon | object | No | Optional tracing metadata for Opticon. |
messages — content shapes
The shape of content depends on the API’s bound InputType:
{
"role": "user",
"content": "Please analyze this text."
}
{
"role": "user",
"content": [
{ "type": "text", "text": "Please analyze this image." },
{
"type": "image",
"image": {
"data": "/9j/4AAQ...",
"media_type": "image/jpeg"
}
}
]
}
{
"role": "user",
"content": [
{ "type": "text", "text": "Please analyze this document." },
{
"type": "file",
"file": {
"data": "<base64_encoded_pdf>",
"filename": "report.pdf",
"media_type": "application/pdf"
}
}
]
}
Each Guard API is bound to a single InputType. Sending a mismatched type returns 400 INVALID_INPUT_TYPE.
opticon — tracing metadata
All fields are optional.
| Field | Type | Description |
|---|
trace_id | string | Custom trace ID. If omitted, the server generates a UUID. |
session_id | string | Groups multiple requests into a single session. |
user_id | string | End-user identifier. |
metadata | object | Free-form key/value payload recorded on the trace. |
tags | array[string] | Filterable tags. |
Credentials stay server-side. You never pass Langfuse public/secret keys in opticon — those are managed server-side by Guardian Bastion. You only pass tracing metadata.
Full example
{
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Tell me about our HBM4 roadmap." }
],
"opticon": {
"session_id": "fab-chat-session",
"user_id": "engineer-park",
"metadata": { "department": "semiconductor", "environment": "production" },
"tags": ["fab-analysis", "sensitive"]
}
}
