{
  "openapi": "3.1.0",
  "info": {
    "title": "Correlate API",
    "version": "0.1.0",
    "summary": "deterministic evidence-correlation engine",
    "description": "Deterministic evidence-correlation engine. Correlate discovers relationships between heterogeneous security observations and never asserts conclusions. Every response is reproducible and accompanied by a machine-readable receipt."
  },
  "servers": [
    {
      "url": "https://correlate.platphormnews.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "PlatPhormBearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "PLATPHORM_API_KEY",
        "description": "Bearer authentication remains accepted for compatibility."
      },
      "PlatPhormHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-PlatPhorm-API-Key",
        "description": "Server-to-server protected actions use X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
      }
    }
  },
  "x-rules": [
    {
      "id": "process-lineage",
      "version": "1",
      "relationshipType": "process_lineage",
      "description": "Relates process_create events where child.parent_process matches a parent process_name on the same host."
    },
    {
      "id": "actor-host-activity",
      "version": "1",
      "relationshipType": "actor_host_activity",
      "description": "Relates consecutive endpoint actions by the same user on the same host into an activity timeline."
    },
    {
      "id": "authenticated-session",
      "version": "1",
      "relationshipType": "authenticated_session",
      "description": "Relates a user_logon to its matching user_logoff for the same user and host pair."
    },
    {
      "id": "remote-authentication",
      "version": "1",
      "relationshipType": "remote_authentication",
      "description": "Relates a network logon to the first endpoint activity by the same user on the destination host."
    },
    {
      "id": "host-network-flow",
      "version": "1",
      "relationshipType": "egress_flow",
      "description": "Relates a source host to an external destination for outbound network connections."
    },
    {
      "id": "process-network",
      "version": "1",
      "relationshipType": "process_egress",
      "description": "Relates a process launch to a following outbound external connection from the same host."
    },
    {
      "id": "c2-beacon",
      "version": "1",
      "relationshipType": "c2_beacon",
      "description": "Groups repeated outbound connections from an internal host to one external IP as beaconing."
    },
    {
      "id": "credential-access",
      "version": "1",
      "relationshipType": "credential_access",
      "description": "Relates sensitive process access (e.g. LSASS) to a following file write on the same host."
    },
    {
      "id": "lateral-movement",
      "version": "1",
      "relationshipType": "lateral_movement",
      "description": "Relates internal host-to-host admin-port connections to subsequent execution on the destination host."
    },
    {
      "id": "service-execution",
      "version": "1",
      "relationshipType": "service_execution",
      "description": "Relates a service creation to a child process spawned by that service on the same host."
    },
    {
      "id": "data-staging",
      "version": "1",
      "relationshipType": "data_staging",
      "description": "Relates archive-tool execution to the archive artifact it stages on the same host."
    },
    {
      "id": "cloud-exfiltration",
      "version": "1",
      "relationshipType": "cloud_exfiltration",
      "description": "Relates an external-bucket cloud upload to the staged archive it exfiltrates."
    },
    {
      "id": "indicator-removal",
      "version": "1",
      "relationshipType": "indicator_removal",
      "description": "Relates deletion of a file/service to its earlier creation on the same host."
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Liveness + readiness probe",
        "responses": {
          "200": {
            "description": "Service healthy"
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "summary": "Versioned health alias",
        "responses": {
          "200": {
            "description": "Service healthy"
          }
        }
      }
    },
    "/api/mcp": {
      "get": {
        "summary": "MCP metadata and usage",
        "responses": {
          "200": {
            "description": "MCP registry"
          }
        }
      },
      "post": {
        "summary": "MCP JSON-RPC 2.0 transport",
        "responses": {
          "200": {
            "description": "JSON-RPC response"
          },
          "204": {
            "description": "Notification accepted"
          }
        }
      }
    },
    "/api/v1/correlate": {
      "post": {
        "summary": "Correlate observations into relationships and activity chains",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      {
                        "type": "object",
                        "required": [
                          "events"
                        ],
                        "properties": {
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          },
                          "metadata": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    ],
                    "description": "Raw SIEM events as an array, or a { events, metadata } bundle."
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "internalNetworks": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "example": [
                          "10.0.0.0/8"
                        ]
                      }
                    }
                  },
                  "datasetName": {
                    "type": "string",
                    "maxLength": 160
                  },
                  "persist": {
                    "type": "boolean",
                    "description": "Persist this independent dataset and result in PlatPhorm Files. Requires X-PlatPhorm-API-Key."
                  },
                  "agentReview": {
                    "type": "boolean",
                    "description": "Request a bounded model-backed review. Requires X-PlatPhorm-API-Key."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Correlation result with entities, relationships, chains and a receipt"
          },
          "400": {
            "description": "Invalid request body"
          },
          "413": {
            "description": "Payload too large"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    },
    "/api/v1/history": {
      "get": {
        "summary": "List or read protected Correlate dataset history from PlatPhorm Files",
        "security": [
          {
            "PlatPhormHeader": []
          }
        ],
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Independent dataset history records"
          },
          "401": {
            "description": "Invalid or missing X-PlatPhorm-API-Key"
          },
          "503": {
            "description": "History storage or platform auth is unavailable"
          }
        }
      }
    },
    "/api/v1/normalize": {
      "post": {
        "summary": "Normalize raw events into canonical observations (no correlation)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      {
                        "type": "object",
                        "required": [
                          "events"
                        ],
                        "properties": {
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          },
                          "metadata": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    ],
                    "description": "Raw SIEM events as an array, or a { events, metadata } bundle."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Canonical observations"
          },
          "400": {
            "description": "Invalid body"
          }
        }
      }
    },
    "/api/v1/explain": {
      "post": {
        "summary": "Explain a relationship or chain with full provenance",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "events"
                ],
                "properties": {
                  "events": {
                    "oneOf": [
                      {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      {
                        "type": "object",
                        "required": [
                          "events"
                        ],
                        "properties": {
                          "events": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "additionalProperties": true
                            }
                          },
                          "metadata": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    ],
                    "description": "Raw SIEM events as an array, or a { events, metadata } bundle."
                  },
                  "config": {
                    "type": "object",
                    "properties": {
                      "internalNetworks": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "example": [
                          "10.0.0.0/8"
                        ]
                      }
                    }
                  },
                  "relationshipId": {
                    "type": "string"
                  },
                  "chainId": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Explanation"
          },
          "404": {
            "description": "Not found in result"
          }
        }
      }
    },
    "/api/v1/rules": {
      "get": {
        "summary": "List correlation rules and their declared factors",
        "responses": {
          "200": {
            "description": "Rule catalog"
          }
        }
      }
    },
    "/api/v1/demo": {
      "get": {
        "summary": "Run correlation over the bundled reference fixture",
        "responses": {
          "200": {
            "description": "Correlation result"
          }
        }
      }
    }
  }
}