{
"components": {
"schemas": {
"CreateExecutionRequest": {
"description": "Request to create a new execution",
"properties": {
"execution": {
"$ref": "#/components/schemas/Execution",
"description": "The execution to create"
}
},
"required": [
"execution"
],
"type": "object"
},
"CreateExecutionResponse": {
"description": "Response after creating an execution",
"type": "object"
},
"Execution": {
"description": "An execution represents the root scope for data collection.\nAll observations are associated with one execution.",
"properties": {
"created_at": {
"description": "When this execution was created",
"format": "date-time",
"type": "string"
},
"id": {
"$ref": "#/components/schemas/ExecutionId",
"description": "Unique identifier for this execution"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"description": "User-defined metadata as key-value pairs",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"name": {
"description": "User-defined name for this execution",
"type": "string"
},
"updated_at": {
"description": "When this execution was last updated",
"format": "date-time",
"type": "string"
}
},
"required": [
"id",
"name",
"created_at",
"updated_at"
],
"type": "object"
},
"ExecutionId": {
"description": "Unique identifier for an execution (UUIDv7)",
"example": "018e9a3a2c1b7e3f8d2a4b5c6d7e8f9a",
"type": "string"
},
"GetExecutionResponse": {
"description": "Response for getting a single execution",
"properties": {
"execution": {
"$ref": "#/components/schemas/Execution",
"description": "The execution"
}
},
"required": [
"execution"
],
"type": "object"
},
"GetObservation": {
"allOf": [
{
"$ref": "#/components/schemas/Observation"
},
{
"properties": {
"payload": {
"$ref": "#/components/schemas/PayloadOrPointerResponse"
}
},
"required": [
"payload"
],
"type": "object"
}
]
},
"GetObservationResponse": {
"properties": {
"observation": {
"$ref": "#/components/schemas/GetObservation"
}
},
"required": [
"observation"
],
"type": "object"
},
"ListExecutionsResponse": {
"description": "Response for listing executions",
"properties": {
"executions": {
"description": "List of executions",
"items": {
"$ref": "#/components/schemas/Execution"
},
"type": "array"
},
"has_next_page": {
"description": "Whether there are more results available",
"type": "boolean"
}
},
"required": [
"executions",
"has_next_page"
],
"type": "object"
},
"ListObservationsResponse": {
"description": "Response for listing observations",
"properties": {
"has_next_page": {
"description": "Whether there are more results available",
"type": "boolean"
},
"observations": {
"description": "List of observations",
"items": {
"$ref": "#/components/schemas/GetObservation"
},
"type": "array"
}
},
"required": [
"observations",
"has_next_page"
],
"type": "object"
},
"LogLevel": {
"description": "Log level for observations",
"enum": [
"Trace",
"Debug",
"Info",
"Warning",
"Error"
],
"type": "string"
},
"Observation": {
"description": "An observation is a single piece of collected data",
"properties": {
"created_at": {
"description": "When this observation was created",
"format": "date-time",
"type": "string"
},
"execution_id": {
"$ref": "#/components/schemas/ExecutionId",
"description": "ID of the execution this observation belongs to"
},
"id": {
"$ref": "#/components/schemas/ObservationId",
"description": "Unique identifier for this observation"
},
"labels": {
"description": "Hierarchical labels for grouping observations\nUses path convention (e.g., \"api/request/headers\")",
"items": {
"type": "string"
},
"type": "array"
},
"log_level": {
"$ref": "#/components/schemas/LogLevel",
"description": "Log level for this observation"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"description": "User-defined metadata as key-value pairs",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"mime_type": {
"description": "MIME type of the payload (e.g., \"text/plain\", \"application/json\")",
"type": "string"
},
"name": {
"description": "User-defined name for this observation",
"type": "string"
},
"observation_type": {
"$ref": "#/components/schemas/ObservationType",
"description": "Type of observation"
},
"parent_span_id": {
"description": "Parent span ID (for tracing integration)",
"nullable": true,
"type": "string"
},
"payload_size": {
"description": "Size of the payload in bytes",
"minimum": 0,
"type": "integer"
},
"source": {
"$ref": "#/components/schemas/SourceInfo",
"description": "Source location where this observation was created",
"nullable": true
}
},
"required": [
"id",
"execution_id",
"name",
"observation_type",
"log_level",
"created_at",
"mime_type",
"payload_size"
],
"type": "object"
},
"ObservationId": {
"description": "Unique identifier for an observation (UUIDv7)",
"example": "018e9a3a2c1b7e3f8d2a4b5c6d7e8f9b",
"type": "string"
},
"ObservationType": {
"description": "Type of observation",
"enum": [
"LogEntry",
"Payload"
],
"type": "string"
},
"PayloadOrPointerResponse": {
"oneOf": [
{
"properties": {
"Text": {
"type": "string"
}
},
"required": [
"Text"
],
"type": "object"
},
{
"properties": {
"Json": {}
},
"required": [
"Json"
],
"type": "object"
},
{
"properties": {
"Markdown": {
"properties": {
"raw": {
"type": "string"
}
},
"required": [
"raw"
],
"type": "object"
}
},
"required": [
"Markdown"
],
"type": "object"
},
{
"properties": {
"InlineBinary": {
"items": {
"format": "int32",
"minimum": 0,
"type": "integer"
},
"type": "array"
}
},
"required": [
"InlineBinary"
],
"type": "object"
},
{
"properties": {
"Pointer": {
"properties": {
"url": {
"type": "string"
}
},
"required": [
"url"
],
"type": "object"
}
},
"required": [
"Pointer"
],
"type": "object"
}
]
},
"SourceInfo": {
"description": "Source location information for an observation",
"properties": {
"column": {
"description": "Optional column number",
"format": "int32",
"minimum": 0,
"nullable": true,
"type": "integer"
},
"file": {
"description": "Source file path",
"type": "string"
},
"line": {
"description": "Line number in the source file",
"format": "int32",
"minimum": 0,
"type": "integer"
}
},
"required": [
"file",
"line"
],
"type": "object"
}
},
"securitySchemes": {
"bearer_auth": {
"bearerFormat": "API Key",
"description": "API key authentication. Set OBSERVATION_TOOLS_API_SECRET on the server to enable.",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"title": "",
"version": ""
},
"openapi": "3.0.3",
"paths": {
"/api/exe": {
"get": {
"operationId": "list_executions",
"parameters": [
{
"description": "Maximum number of results to return",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"minimum": 0,
"nullable": true,
"type": "integer"
}
},
{
"description": "Number of results to skip (for pagination)",
"in": "query",
"name": "offset",
"required": false,
"schema": {
"minimum": 0,
"nullable": true,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListExecutionsResponse"
}
}
},
"description": "List of executions"
},
"400": {
"description": "Bad request"
}
},
"summary": "List all executions",
"tags": [
"executions"
]
},
"post": {
"operationId": "create_execution",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateExecutionRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateExecutionResponse"
}
}
},
"description": "Execution created successfully"
},
"400": {
"description": "Bad request"
}
},
"summary": "Create a new execution",
"tags": [
"executions"
]
}
},
"/api/exe/{execution_id}/obs": {
"get": {
"operationId": "list_observations",
"parameters": [
{
"description": "Execution ID",
"in": "path",
"name": "execution_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Maximum number of results to return",
"in": "query",
"name": "limit",
"required": false,
"schema": {
"minimum": 0,
"nullable": true,
"type": "integer"
}
},
{
"description": "Number of results to skip (for pagination)",
"in": "query",
"name": "offset",
"required": false,
"schema": {
"minimum": 0,
"nullable": true,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListObservationsResponse"
}
}
},
"description": "List of observations"
},
"400": {
"description": "Bad request"
}
},
"summary": "List observations for an execution",
"tags": [
"observations"
]
}
},
"/api/exe/{execution_id}/obs/{observation_id}": {
"get": {
"operationId": "get_observation",
"parameters": [
{
"description": "Execution ID",
"in": "path",
"name": "execution_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Observation ID",
"in": "path",
"name": "observation_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetObservationResponse"
}
}
},
"description": "Observation details"
},
"400": {
"description": "Bad request"
},
"404": {
"description": "Observation not found"
}
},
"summary": "Get a single observation",
"tags": [
"observations"
]
}
},
"/api/exe/{execution_id}/obs/{observation_id}/content": {
"get": {
"operationId": "get_observation_blob",
"parameters": [
{
"description": "Execution ID",
"in": "path",
"name": "execution_id",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Observation ID",
"in": "path",
"name": "observation_id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/octet-stream": {
"schema": {
"items": {
"format": "int32",
"minimum": 0,
"type": "integer"
},
"type": "array"
}
}
},
"description": "Observation blob content"
},
"400": {
"description": "Bad request"
},
"404": {
"description": "Observation blob not found"
}
},
"summary": "Get observation blob content",
"tags": [
"observations"
]
}
},
"/api/exe/{id}": {
"get": {
"operationId": "get_execution",
"parameters": [
{
"description": "Execution ID",
"in": "path",
"name": "id",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetExecutionResponse"
}
}
},
"description": "Execution details"
},
"400": {
"description": "Bad request"
},
"404": {
"description": "Execution not found"
}
},
"summary": "Get a single execution",
"tags": [
"executions"
]
}
}
}
}