{
  "openapi": "3.1.0",
  "info": {
    "title": "epcis.dev — the live doors",
    "version": "0.1.0",
    "description": "The doors that answer on this origin, generated from the typed catalog (src/catalog) the reference pages, /.well-known/agents.json and the npm AGENTS.md check render from — one source, so this document lists exactly the endpoints that answer, and nothing else. Errors are RFC 7807 application/problem+json carrying the standard's own epcisException:* types. The dated launch ledger at /what-ships-today/ is authoritative for everything beyond this document."
  },
  "servers": [
    {
      "url": "https://epcis.dev"
    }
  ],
  "paths": {
    "/translate": {
      "post": {
        "operationId": "translate",
        "summary": "EPCIS 1.1/1.2/2.0 XML in, EPCIS 2.0 JSON-LD out, with a per-job round-trip fidelity report.",
        "description": "EPCIS 1.1/1.2/2.0 XML in, EPCIS 2.0 JSON-LD out, with a per-job round-trip fidelity report. No key, no account: this door answers on https://epcis.dev today. Typed refusals only: epcisException:ValidationException, epcisException:UnsupportedMediaTypeException, epcisException:CaptureLimitExceededException.",
        "requestBody": {
          "required": true,
          "description": "An EPCIS 1.1, 1.2 or 2.0 XML document.",
          "content": {
            "application/xml": {
              "schema": {
                "type": "string"
              }
            },
            "text/xml": {
              "schema": {
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ document, fidelityReport, meteredEvents, sourceSchemaVersion }",
            "headers": {
              "GS1-EPCIS-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "GS1-CBV-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "GS1-Extensions": {
                "schema": {
                  "type": "string"
                }
              },
              "Spine-Translation-Fidelity": {
                "schema": {
                  "type": "string"
                }
              },
              "Spine-Translation-Lossy-Paths": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "document",
                    "fidelityReport",
                    "meteredEvents",
                    "sourceSchemaVersion"
                  ],
                  "properties": {
                    "document": {
                      "type": "object",
                      "description": "The EPCIS 2.0 JSON-LD document."
                    },
                    "fidelityReport": {
                      "type": "object",
                      "description": "The per-job round-trip fidelity report (roundTripClean, lossyPaths)."
                    },
                    "meteredEvents": {
                      "type": "integer"
                    },
                    "sourceSchemaVersion": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "epcisException:ValidationException — translation failed; the fidelity report and per-path schema errors ride the problem body",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "epcisException:CaptureLimitExceededException — payload exceeds the file-size limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "epcisException:UnsupportedMediaTypeException — this door accepts application/xml or text/xml; POST JSON to /validate or /hash",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/validate": {
      "post": {
        "operationId": "validate",
        "summary": "An EPCIS 2.0 document or bare event in; the verdict and per-path errors against the pinned official GS1 EPCIS 2.0.1 schema out.",
        "description": "An EPCIS 2.0 document or bare event in; the verdict and per-path errors against the pinned official GS1 EPCIS 2.0.1 schema out. No key, no account: this door answers on https://epcis.dev today. Typed refusals only: epcisException:ValidationException, epcisException:UnsupportedMediaTypeException, epcisException:CaptureLimitExceededException.",
        "requestBody": {
          "required": true,
          "description": "An EPCISDocument or a bare EPCIS event object.",
          "content": {
            "application/json": {
              "schema": {}
            },
            "application/ld+json": {
              "schema": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ valid, schema: { artefact, version, sha256 }, errors: [{ path, keyword, message }] }",
            "headers": {
              "GS1-EPCIS-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "GS1-CBV-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "GS1-Extensions": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "valid",
                    "schema",
                    "errors"
                  ],
                  "properties": {
                    "valid": {
                      "type": "boolean"
                    },
                    "schema": {
                      "type": "object",
                      "description": "The pinned official schema the verdict is against.",
                      "properties": {
                        "artefact": {
                          "type": "string",
                          "const": "epcis-json-schema.json"
                        },
                        "version": {
                          "type": "string"
                        },
                        "sha256": {
                          "type": "string",
                          "description": "The sha256 pin of the official schema (vendor/gs1/PINS.json).",
                          "const": "0f46ff694efffd8d8ce840a33dfde84228add11b516b8b258f3200740ae210af"
                        }
                      }
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "path": {
                            "type": "string"
                          },
                          "keyword": {
                            "type": "string"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "epcisException:ValidationException — malformed JSON",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "epcisException:CaptureLimitExceededException — payload exceeds the file-size limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "epcisException:UnsupportedMediaTypeException — this door accepts application/json or application/ld+json; POST XML to /translate",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/hash": {
      "post": {
        "operationId": "hash",
        "summary": "An event, an array of events, or an EPCISDocument in; CBV 2.0 §8.9 event hashes out, as ni:///sha-256 URIs.",
        "description": "An event, an array of events, or an EPCISDocument in; CBV 2.0 §8.9 event hashes out, as ni:///sha-256 URIs. No key, no account: this door answers on https://epcis.dev today. Typed refusals only: epcisException:ValidationException, epcisException:UnsupportedMediaTypeException, epcisException:CaptureLimitExceededException.",
        "requestBody": {
          "required": true,
          "description": "A single EPCIS event, an array of events, or an EPCISDocument with epcisBody.eventList.",
          "content": {
            "application/json": {
              "schema": {}
            },
            "application/ld+json": {
              "schema": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "{ algorithm, count, hashes: [ni:///sha-256;…?ver=CBV2.0] }",
            "headers": {
              "GS1-EPCIS-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "GS1-CBV-Version": {
                "schema": {
                  "type": "string"
                }
              },
              "GS1-Extensions": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "algorithm",
                    "count",
                    "hashes"
                  ],
                  "properties": {
                    "algorithm": {
                      "type": "string",
                      "const": "CBV 2.0 §8.9 event hash"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "hashes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "ni:///sha-256;…?ver=CBV2.0"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "epcisException:ValidationException — malformed JSON, or no EPCIS events found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "413": {
            "description": "epcisException:CaptureLimitExceededException — payload exceeds the file-size limit",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "415": {
            "description": "epcisException:UnsupportedMediaTypeException — this door accepts application/json or application/ld+json; POST XML to /translate",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "operationId": "mcp",
        "summary": "The MCP agent door: JSON-RPC 2.0 on this origin. initialize, tools/list and ping answer with no key; the translate tool answers with no key; the keyed tools (capture, query, get_event, trace_epc) answer with a capture key and, without one, answer the typed epcisException:SecurityException 401 as a tool-level error (isError: true).",
        "description": "The MCP agent door: JSON-RPC 2.0 on this origin. initialize, tools/list and ping answer with no key; the translate tool answers with no key; the keyed tools (capture, query, get_event, trace_epc) answer with a capture key and, without one, answer the typed epcisException:SecurityException 401 as a tool-level error (isError: true). No key, no account: this door answers on https://epcis.dev today. Typed refusals only: epcisException:SecurityException.",
        "requestBody": {
          "required": true,
          "description": "A JSON-RPC 2.0 request envelope: { jsonrpc: \"2.0\", id, method, params }.",
          "content": {
            "application/json": {
              "schema": {}
            }
          }
        },
        "responses": {
          "200": {
            "description": "A JSON-RPC 2.0 response envelope; a door refusal is a tool result with isError: true mirroring the gateway's problem document, not a JSON-RPC error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "A JSON-RPC 2.0 response envelope. A door refusal is a tool result with isError: true mirroring the gateway's problem document — it is not a JSON-RPC error."
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 7807 application/problem+json carrying the standard's own epcisException:* types. Match on type, never on prose.",
        "required": [
          "type",
          "title",
          "status"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The epcisException:* problem type."
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          }
        }
      }
    }
  }
}