openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "Engram HTTP API",
    "version": "1.0.0",
    "description": "Execution-memory runtime and read-focused control-plane API. The application or agent remains the decision authority; Engram records recall, declared influence, observations, outcomes and provenance."
  },
  "servers": [
    {
      "url": "{baseUrl}",
      "variables": {
        "baseUrl": {
          "default": "http://localhost:3000"
        }
      }
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Service health and protocol boundary",
        "security": [],
        "responses": {
          "200": {
            "description": "Healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/demo/run": {
      "post": {
        "summary": "Run the deterministic Engram causal demo",
        "description": "Public MVP proof endpoint. External workload execution remains simulated.",
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic Run A -> memory -> Run B proof",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          }
        }
      }
    },
    "/v1/executions": {
      "post": {
        "summary": "Start an execution",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartExecutionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Execution started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["executionId"],
                  "properties": {
                    "executionId": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/executions/{id}/recall": {
      "post": {
        "summary": "Recall comparable operational memory",
        "parameters": [
          { "$ref": "#/components/parameters/ExecutionId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RecallRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Recall result including exposed and rejected candidates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/executions/{id}/decisions": {
      "post": {
        "summary": "Record an application/agent decision and declared memory influence",
        "description": "Engram validates and records the decision; Engram does not choose the action.",
        "parameters": [
          { "$ref": "#/components/parameters/ExecutionId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/DecisionRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Decision recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "409": {
            "description": "Influence/provenance protocol violation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/executions/{id}/observations": {
      "post": {
        "summary": "Append an execution observation",
        "parameters": [
          { "$ref": "#/components/parameters/ExecutionId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ObservationRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Observation recorded"
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/executions/{id}/complete": {
      "post": {
        "summary": "Complete an execution and evaluate memory admission signals",
        "parameters": [
          { "$ref": "#/components/parameters/ExecutionId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CompleteRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Execution completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/executions/{id}/trace": {
      "get": {
        "summary": "Reconstruct execution and memory-to-action trace",
        "parameters": [
          { "$ref": "#/components/parameters/ExecutionId" }
        ],
        "responses": {
          "200": {
            "description": "Execution trace",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/memory/search": {
      "post": {
        "summary": "Low-level operational-memory search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MemorySearchRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked memory candidates",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/mcp/status": {
      "get": {
        "summary": "Inspect CockroachDB Cloud Managed MCP connectivity",
        "responses": {
          "200": {
            "description": "Managed MCP status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/mcp/memories/{id}/provenance": {
      "get": {
        "summary": "Inspect one memory's provenance through Managed MCP",
        "parameters": [
          { "$ref": "#/components/parameters/MemoryId" }
        ],
        "responses": {
          "200": {
            "description": "Read-only provenance result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/overview": {
      "get": {
        "summary": "Control-plane causal/evidence overview",
        "responses": {
          "200": {
            "description": "Overview metrics",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/agents": {
      "get": {
        "summary": "List agents",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericPage" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/executions": {
      "get": {
        "summary": "List executions",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          {
            "name": "agentId",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericPage" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/memories": {
      "get": {
        "summary": "List operational memories",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" },
          {
            "name": "agentId",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericPage" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/influences": {
      "get": {
        "summary": "List memory-to-decision influences",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericPage" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/policies": {
      "get": {
        "summary": "List policy bundles",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericPage" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/policy-assignments": {
      "get": {
        "summary": "List policy assignments",
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Cursor" }
        ],
        "responses": {
          "200": { "$ref": "#/components/responses/GenericPage" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    },
    "/v1/control-plane/memories/{id}/evaluation": {
      "get": {
        "summary": "Inspect evidence-safe evaluation for one memory",
        "parameters": [
          { "$ref": "#/components/parameters/MemoryId" }
        ],
        "responses": {
          "200": {
            "description": "Memory evaluation and interpretation boundary",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "503": { "$ref": "#/components/responses/AuthNotConfigured" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "ENGRAM_API_TOKEN deployment guard. Not production multi-tenant RBAC."
      }
    },
    "parameters": {
      "ExecutionId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      },
      "MemoryId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": { "type": "integer", "minimum": 1, "maximum": 200 }
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": false,
        "schema": { "type": "string" }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid bearer token",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "AuthNotConfigured": {
        "description": "Server API authorization is not configured",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "GenericPage": {
        "description": "Cursor-paginated control-plane result",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "additionalProperties": true
            }
          }
        }
      }
    },
    "schemas": {
      "EvidenceState": {
        "type": "string",
        "enum": ["VERIFIED", "OBSERVED", "SIMULATED", "INFERRED", "PROPOSED", "UNKNOWN"]
      },
      "OutcomeStatus": {
        "type": "string",
        "enum": ["SUCCESS", "FAILURE", "PARTIAL", "COMPENSATED", "ABORTED", "UNKNOWN"]
      },
      "InfluenceType": {
        "type": "string",
        "enum": ["CHANGED_ACTION", "CONSTRAINED_ACTION", "SUPPORTED_ACTION", "CONSIDERED"]
      },
      "Counterfactual": {
        "type": "object",
        "required": ["action", "source", "evidenceState", "explanation"],
        "properties": {
          "action": { "type": "object", "additionalProperties": true },
          "source": {
            "type": "string",
            "enum": ["APPLICATION_DECLARED", "CONTROL_RUN", "SHADOW_RUN", "REPLAY", "UNKNOWN"]
          },
          "evidenceState": { "$ref": "#/components/schemas/EvidenceState" },
          "explanation": { "type": "string", "minLength": 1 },
          "comparisonExecutionId": { "type": "string", "format": "uuid" }
        }
      },
      "MemoryInfluence": {
        "type": "object",
        "required": ["memoryId", "influenceType", "summary"],
        "properties": {
          "memoryId": { "type": "string", "format": "uuid" },
          "retrievalId": { "type": "string", "format": "uuid" },
          "influenceType": { "$ref": "#/components/schemas/InfluenceType" },
          "summary": { "type": "string", "minLength": 1 },
          "relevance": { "type": "number", "minimum": 0, "maximum": 1 },
          "counterfactual": { "$ref": "#/components/schemas/Counterfactual" }
        }
      },
      "StartExecutionRequest": {
        "type": "object",
        "required": ["agentId", "workflowType", "intent", "context", "constraints"],
        "properties": {
          "agentId": { "type": "string", "minLength": 1 },
          "agentVersion": { "type": "string" },
          "workflowType": { "type": "string", "minLength": 1 },
          "intent": { "type": "string", "minLength": 1 },
          "context": { "type": "object", "additionalProperties": true },
          "constraints": { "type": "object", "additionalProperties": true },
          "environmentVersion": { "type": "string" },
          "toolVersion": { "type": "string" },
          "policyVersion": { "type": "string" }
        }
      },
      "RecallRequest": {
        "type": "object",
        "required": ["query"],
        "properties": {
          "query": { "type": "string", "minLength": 1 },
          "status": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/OutcomeStatus" }
          }
        }
      },
      "DecisionRequest": {
        "type": "object",
        "required": ["decisionType", "selectedAction", "reasoningSummary"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "decisionType": { "type": "string", "minLength": 1 },
          "selectedAction": { "type": "object", "additionalProperties": true },
          "alternatives": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          },
          "reasoningSummary": { "type": "string", "minLength": 1 },
          "influences": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/MemoryInfluence" }
          },
          "decidedAt": { "type": "string", "format": "date-time" }
        }
      },
      "ObservationRequest": {
        "type": "object",
        "required": ["type", "payload", "evidenceState"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "type": { "type": "string", "minLength": 1 },
          "payload": { "type": "object", "additionalProperties": true },
          "evidenceState": { "$ref": "#/components/schemas/EvidenceState" },
          "observedAt": { "type": "string", "format": "date-time" },
          "provenance": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          }
        }
      },
      "AdmissionSignal": {
        "type": "object",
        "required": ["kind", "summary", "evidenceState"],
        "properties": {
          "kind": {
            "type": "string",
            "enum": ["UNEXPECTED_FAILURE", "SUCCESSFUL_RECOVERY", "POLICY_VIOLATION", "HUMAN_CORRECTION", "SAFETY_INTERVENTION", "SIGNIFICANT_COST", "NOVEL_CONDITION", "REPEATED_PATTERN"]
          },
          "summary": { "type": "string", "minLength": 1 },
          "evidenceState": { "$ref": "#/components/schemas/EvidenceState" },
          "details": { "type": "object", "additionalProperties": true },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "sourceExecutionIds": {
            "type": "array",
            "minItems": 1,
            "items": { "type": "string", "format": "uuid" },
            "description": "Executions whose evidence supports this memory. Explicit sets must include the execution being completed; every source must exist and belong to the same agent. Duplicate IDs are tolerated and deduplicated by the runtime."
          }
        }
      },
      "CompleteRequest": {
        "type": "object",
        "required": ["status", "summary", "evidenceState"],
        "properties": {
          "status": { "$ref": "#/components/schemas/OutcomeStatus" },
          "summary": { "type": "string", "minLength": 1 },
          "result": { "type": "object", "additionalProperties": true },
          "failureType": { "type": "string" },
          "evidenceState": { "$ref": "#/components/schemas/EvidenceState" },
          "completedAt": { "type": "string", "format": "date-time" },
          "admissionSignals": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/AdmissionSignal" }
          }
        }
      },
      "MemorySearchRequest": {
        "type": "object",
        "required": ["agentId", "query"],
        "properties": {
          "agentId": { "type": "string", "minLength": 1 },
          "executionId": { "type": "string", "format": "uuid" },
          "query": { "type": "string", "minLength": 1 },
          "workflowType": { "type": "string" },
          "environmentVersion": { "type": "string" },
          "limit": { "type": "integer", "minimum": 1, "maximum": 50 }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": ["service", "status", "runtime", "protocolBoundary"],
        "properties": {
          "service": { "type": "string" },
          "status": { "const": "ok" },
          "runtime": { "type": "string" },
          "protocolBoundary": {
            "type": "object",
            "additionalProperties": { "type": "string" }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        },
        "additionalProperties": true
      }
    }
  }
}