{
  "openapi": "3.1.0",
  "info": {
    "title": "BrowserKit Developer API",
    "version": "1.0.0",
    "description": "High-performance, stateless developer utilities and machine-readable endpoints for software engineers and autonomous AI agents. Includes JSON formatting, Base64 conversion, JWT decoding, UUID generation, cryptographic hashing, timestamp conversion, URL encoding, and regex testing.",
    "contact": {
      "name": "BrowserKit Support",
      "url": "https://browserkit.run/contact",
      "email": "support@browserkit.run"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    },
    "x-deprecation-policy": {
      "url": "https://browserkit.run/deprecation-policy",
      "noticePeriodMonths": 12,
      "minimumNoticeMonths": 12,
      "deprecationHeader": "Deprecation",
      "sunsetHeader": "Sunset",
      "signaling": "RFC 8594 Sunset and Deprecation HTTP headers",
      "headers": [
        "Deprecation",
        "Sunset",
        "Link"
      ],
      "policy": "Minimum 12-month advance notice prior to retiring or modifying any public API endpoint."
    },
    "x-ratelimit-policy": {
      "standard": "draft-ietf-httpapi-ratelimit-headers",
      "standardHeaders": "draft-ietf-httpapi-ratelimit-headers",
      "freeTierLimit": 100,
      "proTierLimit": 1000,
      "windowSeconds": 60,
      "headers": [
        "RateLimit-Limit",
        "RateLimit-Remaining",
        "RateLimit-Reset",
        "RateLimit-Policy",
        "Retry-After"
      ]
    }
  },
  "servers": [
    {
      "url": "https://browserkit.run",
      "description": "Production Edge CDN"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getApiCatalog",
        "summary": "Retrieve API catalog and service status",
        "description": "Returns service health, version metadata, and available utility endpoints for automated agent discovery.",
        "responses": {
          "200": {
            "description": "API status and catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiCatalogResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/format-json": {
      "post": {
        "operationId": "formatJson",
        "summary": "Format, beautify, and validate JSON payloads",
        "description": "Parses input JSON, checks syntax validity, detects syntax errors with line/column coordinates, and formats with custom indentation and optional key sorting.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FormatJsonRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON successfully formatted and validated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FormatJsonResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON or syntax error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/base64": {
      "post": {
        "operationId": "processBase64",
        "summary": "Encode or decode Base64 strings",
        "description": "Encodes standard UTF-8 text to RFC 4648 standard or URL-safe Base64, or decodes Base64 back to plain text.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Base64Request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Base64 processing completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Base64Response"
                }
              }
            }
          },
          "400": {
            "description": "Invalid Base64 or request error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/jwt-decode": {
      "post": {
        "operationId": "decodeJwt",
        "summary": "Inspect and decode JSON Web Token (JWT)",
        "description": "Parses a standard JWT (header.payload.signature) statelessly, decodes claims, and evaluates token expiration status without sending secret keys.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/JwtDecodeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT successfully decoded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JwtDecodeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JWT token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/uuid": {
      "get": {
        "operationId": "generateUuid",
        "summary": "Generate cryptographically secure UUID v4 identifiers",
        "description": "Generates one or more RFC 4122 Version 4 random UUIDs using CSPRNG entropy.",
        "parameters": [
          {
            "name": "count",
            "in": "query",
            "required": false,
            "description": "Number of UUIDs to generate (1 to 100). Default is 1.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 1
            }
          },
          {
            "name": "uppercase",
            "in": "query",
            "required": false,
            "description": "Return UUIDs in uppercase format.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "hyphens",
            "in": "query",
            "required": false,
            "description": "Include standard hyphen delimiters.",
            "schema": {
              "type": "boolean",
              "default": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "UUIDs generated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UuidResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/hash": {
      "post": {
        "operationId": "computeHash",
        "summary": "Compute cryptographic checksums and digests",
        "description": "Computes SHA-256, SHA-512, SHA-384, SHA-1, or MD5 cryptographic hashes for any string payload.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HashRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Hash computed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HashResponse"
                }
              }
            }
          },
          "400": {
            "description": "Unsupported algorithm or payload error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/timestamp": {
      "post": {
        "operationId": "convertTimestamp",
        "summary": "Convert Unix epoch timestamps and ISO 8601 dates",
        "description": "Converts Unix timestamps (seconds or milliseconds) to ISO 8601 UTC and formatted dates, or converts ISO strings to Unix timestamps.",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TimestampRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Timestamp converted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TimestampResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid timestamp format",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/url": {
      "post": {
        "operationId": "processUrl",
        "summary": "Percent-encode or decode URLs and query parameters",
        "description": "Applies RFC 3986 percent-encoding or decoding to URLs and parses query parameters into structured JSON.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UrlRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "URL processed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UrlResponse"
                }
              }
            }
          },
          "400": {
            "description": "Malformed URL or encoding error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/regex": {
      "post": {
        "operationId": "testRegex",
        "summary": "Test JavaScript regular expressions against test strings",
        "description": "Executes regular expressions with flags (g, i, m, s, u) against a target string, extracting matching indices and capture groups.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegexRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Regex evaluation completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RegexResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid regex pattern or execution error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Standardized uppercase error code.",
                "example": "NOT_FOUND"
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of the error.",
                "example": "The requested resource does not exist."
              },
              "hint": {
                "type": "string",
                "description": "Actionable resolution hint for developers and AI agents.",
                "example": "Check the OpenAPI specification at /openapi.json or developer documentation at /developers."
              }
            }
          }
        }
      },
      "ApiCatalogResponse": {
        "type": "object",
        "required": ["name", "version", "status", "documentationUrl", "openApiUrl"],
        "properties": {
          "name": { "type": "string", "example": "BrowserKit REST API v1" },
          "version": { "type": "string", "example": "1.0.0" },
          "status": { "type": "string", "example": "operational" },
          "documentationUrl": { "type": "string", "example": "https://browserkit.run/developers" },
          "openApiUrl": { "type": "string", "example": "https://browserkit.run/openapi.json" },
          "endpoints": { "type": "array", "items": { "type": "object" } }
        }
      },
      "FormatJsonRequest": {
        "type": "object",
        "required": ["json"],
        "properties": {
          "json": {
            "type": "string",
            "description": "Raw JSON string payload to format or validate.",
            "example": "{\"service\":\"browserkit\",\"active\":true}"
          },
          "indent": {
            "type": "integer",
            "description": "Indentation spacing in spaces (default: 2, 0 for minified).",
            "default": 2,
            "example": 2
          },
          "sortKeys": {
            "type": "boolean",
            "description": "Sort object keys alphabetically.",
            "default": false,
            "example": true
          }
        }
      },
      "FormatJsonResponse": {
        "type": "object",
        "required": ["valid", "formatted", "rawBytes", "itemCount"],
        "properties": {
          "valid": { "type": "boolean", "example": true },
          "formatted": { "type": "string", "example": "{\n  \"active\": true,\n  \"service\": \"browserkit\"\n}" },
          "rawBytes": { "type": "integer", "example": 45 },
          "itemCount": { "type": "integer", "example": 2 }
        }
      },
      "Base64Request": {
        "type": "object",
        "required": ["action", "data"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["encode", "decode"],
            "description": "Operation to perform: encode or decode.",
            "example": "encode"
          },
          "data": {
            "type": "string",
            "description": "String payload to encode or decode.",
            "example": "Hello BrowserKit"
          },
          "urlSafe": {
            "type": "boolean",
            "description": "Use RFC 4648 §5 URL-safe characters (- and _ without padding).",
            "default": false,
            "example": false
          }
        }
      },
      "Base64Response": {
        "type": "object",
        "required": ["action", "result", "urlSafe"],
        "properties": {
          "action": { "type": "string", "example": "encode" },
          "result": { "type": "string", "example": "SGVsbG8gQnJvd3NlcmtpdA==" },
          "urlSafe": { "type": "boolean", "example": false },
          "originalBytes": { "type": "integer", "example": 16 },
          "encodedLength": { "type": "integer", "example": 24 }
        }
      },
      "JwtDecodeRequest": {
        "type": "object",
        "required": ["token"],
        "properties": {
          "token": {
            "type": "string",
            "description": "Full JSON Web Token string (header.payload.signature).",
            "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsaWNlIiwiaWF0IjoxNTE2MjM5MDIyLCJleHAiOjE5OTk5OTk5OTl9.signature"
          }
        }
      },
      "JwtDecodeResponse": {
        "type": "object",
        "required": ["valid", "header", "payload", "hasSignature", "timing"],
        "properties": {
          "valid": { "type": "boolean", "example": true },
          "header": { "type": "object", "example": { "alg": "HS256", "typ": "JWT" } },
          "payload": { "type": "object", "example": { "sub": "1234567890", "name": "Alice" } },
          "hasSignature": { "type": "boolean", "example": true },
          "timing": {
            "type": "object",
            "properties": {
              "isExpired": { "type": "boolean", "example": false },
              "expiresInSeconds": { "type": "number", "example": 284376000 },
              "issuedAtIso": { "type": "string", "example": "2018-01-18T01:30:22.000Z" },
              "expiresAtIso": { "type": "string", "example": "2033-05-18T03:33:19.000Z" }
            }
          }
        }
      },
      "UuidResponse": {
        "type": "object",
        "required": ["count", "version", "standard", "uuids"],
        "properties": {
          "count": { "type": "integer", "example": 1 },
          "version": { "type": "integer", "example": 4 },
          "standard": { "type": "string", "example": "RFC 4122" },
          "uuids": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["c9b1d620-80be-4a5f-9db0-f212f45ecb12"]
          }
        }
      },
      "HashRequest": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "algorithm": {
            "type": "string",
            "enum": ["SHA-256", "SHA-512", "SHA-384", "SHA-1", "MD5"],
            "default": "SHA-256",
            "description": "Cryptographic digest algorithm.",
            "example": "SHA-256"
          },
          "data": {
            "type": "string",
            "description": "Input text payload to hash.",
            "example": "browserkit"
          }
        }
      },
      "HashResponse": {
        "type": "object",
        "required": ["algorithm", "hash", "length", "bytes"],
        "properties": {
          "algorithm": { "type": "string", "example": "SHA-256" },
          "hash": { "type": "string", "example": "e5c7a9163df478d3ca24d31835bc5ecf23026a7a030dbbb93259b6ce8eb12902" },
          "length": { "type": "integer", "example": 64 },
          "bytes": { "type": "integer", "example": 10 }
        }
      },
      "TimestampRequest": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "number",
            "description": "Unix timestamp in seconds or milliseconds (defaults to current time if omitted).",
            "example": 1763748000
          },
          "iso": {
            "type": "string",
            "description": "ISO 8601 date string to convert to Unix timestamp.",
            "example": "2026-11-21T18:00:00Z"
          }
        }
      },
      "TimestampResponse": {
        "type": "object",
        "required": ["valid", "unixSeconds", "unixMilliseconds", "iso8601", "utc"],
        "properties": {
          "valid": { "type": "boolean", "example": true },
          "unixSeconds": { "type": "integer", "example": 1763748000 },
          "unixMilliseconds": { "type": "integer", "example": 1763748000000 },
          "iso8601": { "type": "string", "example": "2025-11-21T18:00:00.000Z" },
          "utc": { "type": "string", "example": "Fri, 21 Nov 2025 18:00:00 GMT" }
        }
      },
      "UrlRequest": {
        "type": "object",
        "required": ["url"],
        "properties": {
          "action": {
            "type": "string",
            "enum": ["encode", "decode"],
            "default": "encode",
            "example": "encode"
          },
          "url": {
            "type": "string",
            "description": "URL or query string to encode or decode.",
            "example": "https://browserkit.run/search?q=developer tools"
          }
        }
      },
      "UrlResponse": {
        "type": "object",
        "required": ["action", "result", "standard"],
        "properties": {
          "action": { "type": "string", "example": "encode" },
          "result": { "type": "string", "example": "https%3A%2F%2Fbrowserkit.run%2Fsearch%3Fq%3Ddeveloper%20tools" },
          "standard": { "type": "string", "example": "RFC 3986" },
          "parsedUrl": { "type": "object" }
        }
      },
      "RegexRequest": {
        "type": "object",
        "required": ["pattern", "testString"],
        "properties": {
          "pattern": {
            "type": "string",
            "description": "Regular expression pattern.",
            "example": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"
          },
          "flags": {
            "type": "string",
            "description": "Regex flags (e.g., g, i, m). Default: g",
            "default": "g",
            "example": "g"
          },
          "testString": {
            "type": "string",
            "description": "Target string to execute regex matching against.",
            "example": "Contact support@browserkit.run for developer help."
          }
        }
      },
      "RegexResponse": {
        "type": "object",
        "required": ["pattern", "flags", "isValid", "matched", "matchCount", "matches"],
        "properties": {
          "pattern": { "type": "string", "example": "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b" },
          "flags": { "type": "string", "example": "g" },
          "isValid": { "type": "boolean", "example": true },
          "matched": { "type": "boolean", "example": true },
          "matchCount": { "type": "integer", "example": 1 },
          "matches": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "match": { "type": "string" },
                "index": { "type": "integer" }
              }
            }
          }
        }
      }
    }
  }
}
