{"openapi":"3.0.3","info":{"title":"GThree GEO API","version":"1.0.0","description":"Public API surface for the GThree GEO (Generative Engine Optimization) platform — Share of Model benchmarking, nurture drip, Shopify integration, and marketing attribution.","contact":{"name":"GThree","url":"https://gthree.agency"}},"servers":[{"url":"https://gthree.agency","description":"GThree API base URL"}],"tags":[{"name":"benchmark","description":"Share of Model benchmarking endpoints."},{"name":"demo","description":"Demo request and conversion capture."},{"name":"marketing","description":"Marketing touchpoint and outbound enrollment."},{"name":"nurture","description":"Nurture drip scheduling and unsubscribe."},{"name":"shopify","description":"Shopify OAuth and audit endpoints."}],"paths":{"/api/benchmark":{"post":{"tags":["benchmark"],"summary":"Run a Share of Model benchmark","description":"Returns Share of Model (SoM) percentages for a brand and optional competitor across GPT-4o, GPT-4o Mini, Claude Sonnet 4, and Claude 3.5 Sonnet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brandDomain"],"properties":{"brandDomain":{"type":"string","example":"example.com","description":"Brand store domain (protocol and www. optional)."},"competitorDomain":{"type":"string","example":"competitor.com","description":"Optional competitor domain; omit for solo mode."}}}}}},"responses":{"200":{"description":"Benchmark results","content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["solo","compare"]},"results":{"type":"object","properties":{"overall":{"type":"object","properties":{"brand":{"type":"integer"},"competitor":{"type":"integer"}}},"byModel":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"model":{"type":"string"},"brand":{"type":"integer"},"competitor":{"type":"integer"}}}},"byQueryType":{"type":"object","additionalProperties":true}}},"summary":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"brandDomain missing"},"500":{"description":"Benchmark failed"}}}},"/api/demo-request":{"post":{"tags":["demo"],"summary":"Submit a demo request from the SoM Benchmarking Tool","description":"Captures a demo lead, schedules a 4-email nurture drip, and notifies the GThree team.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"storeUrl":{"type":"string"},"gapArea":{"type":"string","enum":["product-research","comparative-shopping","buying-advice","brand-visibility","other"]},"contactTime":{"type":"string","enum":["morning","afternoon","evening"]},"somScore":{"type":"integer","nullable":true},"category":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Demo request captured","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"emailsScheduled":{"type":"integer","example":4}}}}}},"400":{"description":"Name and email required"},"500":{"description":"Failed to submit request"}}}},"/api/demo-conversion":{"post":{"tags":["demo"],"summary":"Capture a demo-page conversion with UTM attribution","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"store_url":{"type":"string"},"message":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_content":{"type":"string"},"utm_term":{"type":"string"}}}}}},"responses":{"200":{"description":"Conversion captured","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"conversion_id":{"type":"integer"}}}}}},"400":{"description":"Name and email required"},"500":{"description":"Submission failed"}}}},"/api/marketing-touchpoints":{"get":{"tags":["marketing"],"summary":"List active marketing touchpoints (UTM templates)","responses":{"200":{"description":"Array of active touchpoints","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"type":{"type":"string"},"base_url":{"type":"string"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"utm_content":{"type":"string"},"utm_term":{"type":"string"},"is_active":{"type":"boolean"}}}}}}}}}},"/api/admin/outbound/enroll":{"post":{"tags":["marketing"],"summary":"Bulk-enroll outbound contacts into the nurture drip","description":"Admin-only. Requires Authorization: Bearer ${ADMIN_SECRET}.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["contacts"],"properties":{"contacts":{"type":"array","items":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"storeUrl":{"type":"string"},"somScore":{"type":"integer"},"category":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Enroll results","content":{"application/json":{"schema":{"type":"object","properties":{"enrolled":{"type":"integer"},"skipped":{"type":"integer"},"errors":{"type":"integer"},"detail":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"contacts must be an array"},"401":{"description":"Unauthorized"}}}},"/api/nurture/send":{"post":{"tags":["nurture"],"summary":"Trigger the nurture scheduler (public, cron-driven)","description":"Pulls due emails from nurture_queue and sends them. Idempotent; safe to call repeatedly.","responses":{"200":{"description":"Send results","content":{"application/json":{"schema":{"type":"object","properties":{"processed":{"type":"integer"},"errors":{"type":"integer"}}}}}},"500":{"description":"Cron error"}}}},"/api/nurture/unsubscribe":{"get":{"tags":["nurture"],"summary":"One-click unsubscribe (cancels remaining drip emails)","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"integer"}},{"name":"token","in":"query","required":true,"schema":{"type":"string","description":"Base64-encoded prospect email."}}],"responses":{"200":{"description":"HTML confirmation page"},"400":{"description":"Missing parameters"},"500":{"description":"Unsubscribe failed"}}}},"/shopify/connect":{"get":{"tags":["shopify"],"summary":"Begin the Shopify OAuth flow","parameters":[{"name":"shop","in":"query","required":true,"schema":{"type":"string","example":"acme.myshopify.com"}}],"responses":{"302":{"description":"Redirect to Shopify authorize URL"},"400":{"description":"Invalid shop domain"}}}},"/shopify/callback":{"get":{"tags":["shopify"],"summary":"Shopify OAuth callback — exchanges code, runs audit","parameters":[{"name":"code","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"shop","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to /shopify/audit/:id"},"400":{"description":"Invalid or expired OAuth state"},"500":{"description":"OAuth or audit failed"}}}},"/shopify/audit/{id}":{"get":{"tags":["shopify"],"summary":"Render an audit result page","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Audit HTML page"},"404":{"description":"Audit not found"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"ADMIN_SECRET token for admin endpoints."}}}}