{"openapi":"3.1.0","info":{"title":"BXSS URL Checker API","version":"1.0.0","description":"BXSS URL Checker is a simple service for checking URLs and retrieving basic HTTP response information. Authenticate with an API key from your account page. Keys are sent in the `X-API-Key` header (recommended, used by Zapier) or as `Authorization: Bearer <key>`.","contact":{"name":"BXSS URL Checker Support","email":"support@bxss.site"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.urlchecker.bxss.site","description":"Production"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"tags":[{"name":"Checks"},{"name":"System"}],"paths":{"/health":{"get":{"tags":["System"],"summary":"Service health","description":"Returns service status. Requires no authentication.","security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","const":"ok"}}}}}}}}},"/v1/whoami":{"get":{"tags":["Checks"],"summary":"Current account","description":"Returns the authenticated account identity. Ideal as an authentication test / connection label source.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Account identity.","content":{"application/json":{"schema":{"type":"object","required":["email","created_at"],"properties":{"email":{"type":"string","format":"email","example":"you@example.com"},"created_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid API key is required."}}}}}}}},"/v1/check":{"post":{"tags":["Checks"],"summary":"Check a URL","description":"Checks a public HTTP or HTTPS URL and stores the result. Redirects are followed (max 5). Only http and https URLs are allowed; requests to private, local, or reserved network addresses are rejected.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","description":"The HTTP or HTTPS URL to check.","example":"https://example.com"},"method":{"type":"string","enum":["GET","HEAD"],"default":"GET","description":"HTTP method to use."}}}}}},"responses":{"201":{"description":"Check completed","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","url","final_url","status_code","response_time_ms","content_type","response_size","title","checked_at"],"properties":{"id":{"type":"string","description":"Stable unique ID of the check.","example":"check_7k3f9x2m1qpzw4dn"},"url":{"type":"string","description":"The URL that was requested.","example":"https://example.com"},"final_url":{"type":["string","null"],"description":"Final URL after redirects.","example":"https://example.com/"},"status_code":{"type":["integer","null"],"description":"HTTP status code.","example":200},"response_time_ms":{"type":["integer","null"],"description":"Response time in milliseconds.","example":143},"content_type":{"type":["string","null"],"description":"Content-Type without parameters.","example":"text/html"},"response_size":{"type":["integer","null"],"description":"Response size in bytes.","example":1256},"title":{"type":["string","null"],"description":"Page title when the response is HTML.","example":"Example Domain"},"checked_at":{"type":"string","format":"date-time","description":"When the check finished.","example":"2026-08-15T10:00:00Z"}}}}}},"400":{"description":"Please provide a valid HTTP or HTTPS URL.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"INVALID_URL","message":"Please provide a valid HTTP or HTTPS URL."}}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid API key is required."}}}}},"422":{"description":"The URL could not be checked (timeout, too many redirects, or unreachable).","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"TIMEOUT","message":"The URL could not be checked (timeout, too many redirects, or unreachable)."}}}}},"429":{"description":"Rate limit exceeded. Try again soon.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Try again soon."}}}}}}}},"/v1/checks":{"get":{"tags":["Checks"],"summary":"List recent checks","description":"Returns your most recent URL checks, newest first, with stable IDs. Suitable for polling.","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Maximum number of checks to return."}],"responses":{"200":{"description":"A JSON array of checks, newest first.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["id","url","final_url","status_code","response_time_ms","content_type","response_size","title","checked_at"],"properties":{"id":{"type":"string","description":"Stable unique ID of the check.","example":"check_7k3f9x2m1qpzw4dn"},"url":{"type":"string","description":"The URL that was requested.","example":"https://example.com"},"final_url":{"type":["string","null"],"description":"Final URL after redirects.","example":"https://example.com/"},"status_code":{"type":["integer","null"],"description":"HTTP status code.","example":200},"response_time_ms":{"type":["integer","null"],"description":"Response time in milliseconds.","example":143},"content_type":{"type":["string","null"],"description":"Content-Type without parameters.","example":"text/html"},"response_size":{"type":["integer","null"],"description":"Response size in bytes.","example":1256},"title":{"type":["string","null"],"description":"Page title when the response is HTML.","example":"Example Domain"},"checked_at":{"type":"string","format":"date-time","description":"When the check finished.","example":"2026-08-15T10:00:00Z"}}}}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid API key is required."}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded."}}}}}}}},"/v1/checks/{id}":{"get":{"tags":["Checks"],"summary":"Get a check by ID","description":"Returns one URL check belonging to the authenticated account.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Check ID."}],"responses":{"200":{"description":"The check.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","url","final_url","status_code","response_time_ms","content_type","response_size","title","checked_at"],"properties":{"id":{"type":"string","description":"Stable unique ID of the check.","example":"check_7k3f9x2m1qpzw4dn"},"url":{"type":"string","description":"The URL that was requested.","example":"https://example.com"},"final_url":{"type":["string","null"],"description":"Final URL after redirects.","example":"https://example.com/"},"status_code":{"type":["integer","null"],"description":"HTTP status code.","example":200},"response_time_ms":{"type":["integer","null"],"description":"Response time in milliseconds.","example":143},"content_type":{"type":["string","null"],"description":"Content-Type without parameters.","example":"text/html"},"response_size":{"type":["integer","null"],"description":"Response size in bytes.","example":1256},"title":{"type":["string","null"],"description":"Page title when the response is HTML.","example":"Example Domain"},"checked_at":{"type":"string","format":"date-time","description":"When the check finished.","example":"2026-08-15T10:00:00Z"}}}}}},"401":{"description":"A valid API key is required.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"UNAUTHORIZED","message":"A valid API key is required."}}}}},"404":{"description":"No URL check was found with that ID.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"INVALID_URL"},"message":{"type":"string","example":"Please provide a valid HTTP or HTTPS URL."}}}}},"example":{"error":{"code":"NOT_FOUND","message":"No URL check was found with that ID."}}}}}}}}},"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key from your BXSS URL Checker account (preferred for Zapier)."},"bearerAuth":{"type":"http","scheme":"bearer","description":"API key sent as a Bearer token."}}}}