{
  "openapi": "3.1.0",
  "info": {
    "title": "EdgeDocAPI",
    "version": "2.0.0",
    "summary": "Zero-retention edge micro-API for AI & RAG document preparation",
    "description": "High-margin B2B document & web-content preparation API on Cloudflare Workers. Convert URLs/HTML to clean LLM-ready Markdown, split documents into deterministic semantic RAG chunks, and extract structured OpenGraph/JSON-LD metadata with zero data retention.",
    "termsOfService": "https://docopsapi.com/terms",
    "contact": {
      "name": "EdgeDocAPI Support",
      "url": "https://docopsapi.com",
      "email": "support@docopsapi.com"
    }
  },
  "servers": [
    {
      "url": "https://api.docopsapi.com",
      "description": "Production Edge API"
    },
    {
      "url": "https://docopsapi.com",
      "description": "Portal & Billing Host"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "edk_live_...",
        "description": "API key prefixed with edk_live_ supplied via Authorization: Bearer <key>"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Alternative header for supplying your edk_live_... API key"
      }
    },
    "headers": {
      "X-RateLimit-Remaining": {
        "description": "Remaining requests in the current 60-second sliding window",
        "schema": {
          "type": "integer"
        }
      },
      "X-RateLimit-Reset": {
        "description": "Unix epoch timestamp (seconds) when the sliding rate window resets",
        "schema": {
          "type": "integer"
        }
      },
      "X-Quota-Used": {
        "description": "Requests consumed in the current UTC billing month",
        "schema": {
          "type": "integer"
        }
      },
      "X-Request-Id": {
        "description": "Unique request correlation ID",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "INVALID_API_KEY"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "UrlToMarkdownRequest": {
        "type": "object",
        "description": "Provide either a public https:// url or a raw html string (max 2MB).",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/docs"
          },
          "html": {
            "type": "string",
            "example": "<article><h1>Hello</h1><p>World</p></article>"
          },
          "include_links": {
            "type": "boolean",
            "default": true
          },
          "include_images": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "UrlToMarkdownResponse": {
        "type": "object",
        "required": [
          "source_url",
          "title",
          "markdown",
          "estimated_tokens",
          "word_count",
          "char_count"
        ],
        "properties": {
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "markdown": {
            "type": "string"
          },
          "estimated_tokens": {
            "type": "integer"
          },
          "word_count": {
            "type": "integer"
          },
          "char_count": {
            "type": "integer"
          }
        }
      },
      "RagChunkRequest": {
        "type": "object",
        "description": "Provide either content (text/markdown/html) or html.",
        "properties": {
          "content": {
            "type": "string"
          },
          "html": {
            "type": "string"
          },
          "format": {
            "type": "string",
            "enum": [
              "text",
              "markdown",
              "html"
            ],
            "default": "markdown"
          },
          "max_tokens": {
            "type": "integer",
            "minimum": 32,
            "maximum": 8192,
            "default": 512
          },
          "overlap": {
            "type": "integer",
            "minimum": 0,
            "maximum": 8191,
            "default": 64
          },
          "source": {
            "type": "object",
            "properties": {
              "url": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "document_id": {
                "type": "string"
              }
            }
          }
        }
      },
      "RagChunkResponse": {
        "type": "object",
        "required": [
          "chunks",
          "total_chunks",
          "total_tokens_estimate",
          "max_tokens",
          "overlap",
          "input_format"
        ],
        "properties": {
          "chunks": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "index",
                "text",
                "token_estimate",
                "char_start",
                "char_end",
                "section_heading",
                "metadata"
              ],
              "properties": {
                "index": {
                  "type": "integer"
                },
                "text": {
                  "type": "string"
                },
                "token_estimate": {
                  "type": "integer"
                },
                "char_start": {
                  "type": "integer"
                },
                "char_end": {
                  "type": "integer"
                },
                "section_heading": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "metadata": {
                  "type": "object"
                }
              }
            }
          },
          "total_chunks": {
            "type": "integer"
          },
          "total_tokens_estimate": {
            "type": "integer"
          },
          "max_tokens": {
            "type": "integer"
          },
          "overlap": {
            "type": "integer"
          },
          "input_format": {
            "type": "string",
            "enum": [
              "text",
              "markdown",
              "html"
            ]
          }
        }
      },
      "ExtractMetadataRequest": {
        "type": "object",
        "description": "Provide either a public https:// url or raw html string (max 2MB).",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "html": {
            "type": "string"
          }
        }
      },
      "ExtractMetadataResponse": {
        "type": "object",
        "required": [
          "source_url",
          "title",
          "description",
          "canonical_url",
          "language",
          "open_graph",
          "twitter",
          "json_ld",
          "headings",
          "outbound_links"
        ],
        "properties": {
          "source_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "canonical_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "language": {
            "type": [
              "string",
              "null"
            ]
          },
          "open_graph": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "twitter": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "json_ld": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "headings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "level": {
                  "type": "integer"
                },
                "text": {
                  "type": "string"
                }
              }
            }
          },
          "outbound_links": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "href": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "rel": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "external": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/health": {
      "get": {
        "summary": "Public liveness and version check",
        "operationId": "getHealth",
        "responses": {
          "200": {
            "description": "Service healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "service": {
                      "type": "string",
                      "example": "edge-doc-api"
                    },
                    "version": {
                      "type": "string",
                      "example": "2.0.0"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/url-to-markdown": {
      "post": {
        "summary": "Convert a public HTTPS URL or raw HTML to clean LLM-ready Markdown",
        "operationId": "urlToMarkdown",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UrlToMarkdownRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Clean Markdown and estimated token count",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlToMarkdownResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON or invalid URL scheme",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Invalid/revoked API key or SSRF target blocked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Payload exceeds 2MB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable/empty content (quota refunded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Global spend/concurrency circuit breaker active",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/rag-chunk": {
      "post": {
        "summary": "Deterministically split text, Markdown, or HTML into semantic RAG chunks",
        "operationId": "ragChunk",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RagChunkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Deterministic JSON chunks ready for vector DB ingestion",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RagChunkResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Invalid/revoked API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Payload exceeds 2MB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Empty/unprocessable content (quota refunded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Global spend circuit breaker active",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v1/extract-metadata": {
      "post": {
        "summary": "Extract OpenGraph, Twitter Cards, JSON-LD, canonical URL, headings, and outbound links",
        "operationId": "extractMetadata",
        "security": [
          {
            "BearerAuth": []
          },
          {
            "ApiKeyHeader": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExtractMetadataRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Structured page metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractMetadataResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request payload or URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Invalid/revoked API key or SSRF target blocked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "413": {
            "description": "Payload exceeds 2MB limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "No extractable metadata or unsupported content type (quota refunded)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit or monthly quota exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "503": {
            "description": "Global spend/concurrency circuit breaker active",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}