{"openapi":"3.0.3","info":{"title":"Shell City API","version":"1.0.0","description":"Web data extraction API marketplace built for AI agents. Scrape any URL for clean markdown or extract structured data using JSON schemas. Pay per call — 1,000 free credits included with every new API key.","contact":{"name":"Shell City Support","url":"https://shellcity.polsia.app/docs"},"x-logo":{"url":"https://shellcity.polsia.app/logo.png"}},"servers":[{"url":"https://shellcity.polsia.app","description":"Production server"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Keys","description":"API key management"},{"name":"Scrape","description":"Web scraping — returns clean markdown"},{"name":"Extract","description":"Structured data extraction using JSON schema"},{"name":"Usage","description":"Usage analytics and request history"},{"name":"Credits","description":"Credit balance and purchasing"}],"paths":{"/v1/keys":{"post":{"tags":["Keys"],"summary":"Create a new API key","description":"Creates a new API key with 1,000 free credits. No authentication required.","operationId":"createApiKey","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address for the API key (optional)"},"name":{"type":"string","description":"Friendly name for this key (optional)"}}}}}},"responses":{"200":{"description":"API key created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"api_key":{"type":"string","example":"sc_live_xxxxxxxxxxxx"},"credits":{"type":"integer","example":100},"message":{"type":"string","example":"1,000 free credits included"}}}}}}}}},"/v1/scrape":{"post":{"tags":["Scrape"],"summary":"Scrape a URL and get clean markdown","description":"Fetches any URL and returns clean markdown content. Costs 1 credit ($0.001) per request.","operationId":"scrapeUrl","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The URL to scrape","example":"https://example.com"}}}}}},"responses":{"200":{"description":"URL scraped successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"},"markdown":{"type":"string","description":"Clean markdown content of the page"},"credits_used":{"type":"integer","example":1},"credits_remaining":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Insufficient credits — purchase more at /v1/credits/checkout"},"422":{"description":"Invalid URL or request body"}}}},"/v1/extract":{"post":{"tags":["Extract"],"summary":"Extract structured data from a URL","description":"Fetches a URL and extracts structured data matching a JSON schema using LLM-based extraction. Costs 5 credits ($0.005) per request.","operationId":"extractData","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","schema"],"properties":{"url":{"type":"string","format":"uri","description":"The URL to extract data from","example":"https://example.com/product"},"schema":{"type":"object","description":"JSON schema describing the data to extract","example":{"title":"string","price":"number","description":"string"}},"prompt":{"type":"string","description":"Optional extraction instructions"}}}}}},"responses":{"200":{"description":"Data extracted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"url":{"type":"string"},"data":{"type":"object","description":"Extracted data matching the provided schema"},"credits_used":{"type":"integer","example":5},"credits_remaining":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"},"402":{"description":"Insufficient credits"},"422":{"description":"Invalid URL, schema, or request body"}}}},"/v1/usage":{"get":{"tags":["Usage"],"summary":"Get usage statistics","description":"Returns usage statistics for your API key.","operationId":"getUsage","responses":{"200":{"description":"Usage statistics","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"total_requests":{"type":"integer"},"total_credits_used":{"type":"integer"},"requests_today":{"type":"integer"},"requests_this_week":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/usage/history":{"get":{"tags":["Usage"],"summary":"Get detailed request history","description":"Returns a paginated list of recent API requests.","operationId":"getUsageHistory","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50},"description":"Number of records to return"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"Request history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"history":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/credits":{"get":{"tags":["Credits"],"summary":"Get credit balance","description":"Returns current credit balance and recent transactions.","operationId":"getCredits","responses":{"200":{"description":"Credit balance and transaction history","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"credits":{"type":"integer","description":"Current credit balance"},"transactions":{"type":"array","items":{"type":"object"}}}}}}},"401":{"description":"Missing or invalid API key"}}}},"/v1/credits/packages":{"get":{"tags":["Credits"],"summary":"List available credit packages","description":"Returns available credit packages and pricing. No authentication required.","operationId":"getCreditPackages","security":[],"responses":{"200":{"description":"Credit packages","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"credits":{"type":"integer"},"price_usd":{"type":"number"}}}}}}}}}}}},"/v1/credits/checkout":{"post":{"tags":["Credits"],"summary":"Create a checkout session to purchase credits","description":"Creates a Stripe checkout session to purchase additional credits.","operationId":"createCheckout","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["package_id"],"properties":{"package_id":{"type":"string","description":"ID of the credit package to purchase (from /v1/credits/packages)"},"success_url":{"type":"string","format":"uri","description":"URL to redirect to after successful payment"},"cancel_url":{"type":"string","format":"uri","description":"URL to redirect to if payment is cancelled"}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"checkout_url":{"type":"string","format":"uri"},"session_id":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key"}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Shell City API key. Format: sc_live_xxxxxxxxxxxx. Get one free at /v1/keys."}}}}