{"openapi":"3.1.0","info":{"title":"Scrapiq","description":"Turn any URL into clean, structured JSON for LLM/RAG pipelines. Submit a URL, optionally with a JSON schema, and get back clean text, markdown, or structured fields ready for fine-tuning or RAG ingestion.","contact":{"name":"Scrapiq","url":"https://github.com/NG-PR0JECT/scrapiq"},"license":{"name":"MIT"},"version":"0.1.0"},"paths":{"/":{"get":{"tags":["Info"],"summary":"Root","description":"Root endpoint with a quick-start example.","operationId":"root__get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Root  Get"}}}}}}},"/health":{"get":{"tags":["System"],"summary":"Health","description":"Health check — used by uptime monitors.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/extract":{"post":{"tags":["Extraction"],"summary":"Extract structured data from a URL","description":"Fetch a URL and return clean text, markdown, or structured fields.\n\n- **format=text**: clean plain text (boilerplate removed)\n- **format=markdown**: clean markdown with links\n- **format=json** (with schema): structured fields per the schema\n- **format=json** (no schema): wrapped raw text under `data.text`","operationId":"extract_endpoint_v1_extract_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/signup":{"post":{"tags":["Auth"],"summary":"Signup","description":"Create an account and return an API key.\n\nIdempotent: signing up with an existing email returns the existing key\n(same plan preserved) rather than erroring.","operationId":"signup_v1_signup_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/usage":{"get":{"tags":["Auth"],"summary":"Usage","description":"Return today's quota usage for an API key.\n\nPass the key via `?api_key=` query param or `X-API-Key` header.","operationId":"usage_v1_usage_get","parameters":[{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key"}},{"name":"x_api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X Api Key"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/checkout":{"get":{"tags":["Billing"],"summary":"Billing Checkout","description":"Return a checkout URL for upgrading to `plan`.\n\nIn stub mode (no Polar token) the URL points at our own confirm endpoint.","operationId":"billing_checkout_v1_billing_checkout_get","parameters":[{"name":"plan","in":"query","required":false,"schema":{"type":"string","default":"pro","title":"Plan"}},{"name":"email","in":"query","required":false,"schema":{"type":"string","default":"","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/confirm":{"get":{"tags":["Billing"],"summary":"Billing Confirm","description":"Stub-mode simulated checkout success — upgrades the user's plan.\n\nOnly meaningful until a real Polar.sh token is configured. In production\n(token set) this endpoint returns 404 and upgrades flow via the webhook.\n\nWhen the client accepts HTML (a browser), redirect back to /pricing with a\nsuccess flag instead of returning raw JSON.","operationId":"billing_confirm_v1_billing_confirm_get","parameters":[{"name":"plan","in":"query","required":false,"schema":{"type":"string","default":"pro","title":"Plan"}},{"name":"email","in":"query","required":false,"schema":{"type":"string","default":"","title":"Email"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/billing/webhook":{"post":{"tags":["Billing"],"summary":"Billing Webhook","description":"Polar.sh webhook receiver. Updates a user's plan on payment events.","operationId":"billing_webhook_v1_billing_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Billing Webhook V1 Billing Webhook Post"}}}}}}},"/v1/events":{"post":{"tags":["Analytics"],"summary":"Events","description":"Record a server-side event (conversion funnel / source attribution).","operationId":"events_v1_events_post","parameters":[{"name":"x_api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X Api Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Events V1 Events Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/stats":{"get":{"tags":["Analytics"],"summary":"Stats","description":"Aggregate stats for MRR / funnel reporting (public, non-sensitive).","operationId":"stats_v1_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Stats V1 Stats Get"}}}}}}}},"components":{"schemas":{"CheckoutResponse":{"properties":{"plan":{"type":"string","title":"Plan"},"email":{"type":"string","title":"Email"},"checkout_url":{"type":"string","title":"Checkout Url"},"provider":{"type":"string","title":"Provider"}},"type":"object","required":["plan","email","checkout_url","provider"],"title":"CheckoutResponse","description":"A checkout URL for upgrading to a paid plan."},"EventRequest":{"properties":{"event_type":{"type":"string","title":"Event Type","description":"e.g. signup, extract, checkout"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"utm_source"},"campaign":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Campaign","description":"utm_campaign"}},"type":"object","required":["event_type"],"title":"EventRequest","description":"Server-side conversion/usage event."},"ExtractRequest":{"properties":{"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","description":"URL to fetch and extract from"},"schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Schema","description":"Optional JSON schema describing fields to extract. If omitted, returns raw cleaned text."},"format":{"type":"string","enum":["json","text","markdown"],"title":"Format","description":"Output format. 'json' for structured extraction, 'text' for plain text, 'markdown' for clean markdown.","default":"json"},"include_metadata":{"type":"boolean","title":"Include Metadata","description":"Include page metadata (title, description, author, date) in the response.","default":true}},"type":"object","required":["url"],"title":"ExtractRequest","description":"Request to extract structured data from a URL."},"ExtractResponse":{"properties":{"url":{"type":"string","title":"Url"},"format":{"type":"string","title":"Format"},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data","description":"Structured data extracted according to the schema. None if format != 'json'."},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Cleaned text or markdown content. None if format == 'json'."},"metadata":{"anyOf":[{"$ref":"#/components/schemas/PageMetadata"},{"type":"null"}]},"cached":{"type":"boolean","title":"Cached","default":false},"extraction_time_ms":{"type":"integer","title":"Extraction Time Ms"}},"type":"object","required":["url","format","extraction_time_ms"],"title":"ExtractResponse","description":"Response with extracted data."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthResponse":{"properties":{"status":{"type":"string","enum":["ok","degraded","down"],"title":"Status"},"version":{"type":"string","title":"Version"},"cache_size":{"type":"integer","title":"Cache Size"}},"type":"object","required":["status","version","cache_size"],"title":"HealthResponse","description":"Health check response."},"PageMetadata":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"author":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Author"},"published_date":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published Date"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"canonical_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical Url"},"word_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Word Count"}},"type":"object","title":"PageMetadata","description":"Metadata about the fetched page."},"SignupRequest":{"properties":{"email":{"type":"string","title":"Email","description":"Email address to associate with the API key"}},"type":"object","required":["email"],"title":"SignupRequest","description":"Create an account / API key."},"SignupResponse":{"properties":{"email":{"type":"string","title":"Email"},"api_key":{"type":"string","title":"Api Key"},"plan":{"type":"string","title":"Plan"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["email","api_key","plan","created_at"],"title":"SignupResponse","description":"Response to a signup request."},"UsageResponse":{"properties":{"api_key":{"type":"string","title":"Api Key"},"plan":{"type":"string","title":"Plan"},"used":{"type":"integer","title":"Used"},"quota":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Quota"},"date":{"type":"string","title":"Date"}},"type":"object","required":["api_key","plan","used","quota","date"],"title":"UsageResponse","description":"Quota usage for the calling API key."},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}