{"openapi":"3.1.0","info":{"title":"TagHelper API","version":"1.0.0","description":"Programmatically run GTM container audits, retrieve scores, and integrate TagHelper into your CI/CD pipeline.","contact":{"url":"https://taghelper.io/docs"}},"servers":[{"url":"https://taghelper.io/api/v1"}],"security":[{"BearerAuth":[]}],"paths":{"/scan":{"post":{"operationId":"startScan","summary":"Start a GTM container audit","description":"Begins an asynchronous audit of a GTM container. Returns a job ID to poll for status.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Audit job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/scan/{jobId}":{"get":{"operationId":"getScanStatus","summary":"Get audit job status","description":"Poll this endpoint to check whether an audit has completed.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The job ID returned by POST /scan"}],"responses":{"200":{"description":"Job status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobStatus"}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/scan/{jobId}/result":{"get":{"operationId":"getScanResult","summary":"Get full audit results","description":"Retrieve detailed audit results including scores, issues, detected platforms, and recommendations. Only available after the job status is 'completed'.","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"The job ID returned by POST /scan"}],"responses":{"200":{"description":"Full audit results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResult"}}}},"404":{"description":"Job or audit not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key with th_live_ or th_test_ prefix, passed as Bearer token."}},"schemas":{"ScanRequest":{"type":"object","required":["container_id"],"properties":{"container_id":{"type":"string","description":"GTM container ID (e.g. \"GTM-XXXXXX\") or URL","example":"GTM-XXXXXX"},"workspace_type":{"type":"string","enum":["ecommerce","lead_generation"],"default":"ecommerce","description":"Type of workspace to optimize audit for"}}},"ScanResponse":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","running","completed","failed"]}}},"JobStatus":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"input_type":{"type":"string","enum":["gtm_id","url","upload"]},"input_value":{"type":"string"},"workspace_type":{"type":"string","enum":["ecommerce","lead_generation"]},"gtm_container_id":{"type":"string","nullable":true},"audit_id":{"type":"string","format":"uuid","nullable":true},"score":{"type":"number","nullable":true},"score_label":{"type":"string","enum":["Excellent","Good","Needs Improvement","Basic","Critical"],"nullable":true},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"AuditResult":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"score":{"type":"number","minimum":0,"maximum":100},"score_label":{"type":"string","enum":["Excellent","Good","Needs Improvement","Basic","Critical"]},"workspace_type":{"type":"string","enum":["ecommerce","lead_generation"]},"gtm_container_id":{"type":"string"},"summary":{"type":"string"},"category_scores":{"$ref":"#/components/schemas/CategoryScores"},"platforms_detected":{"$ref":"#/components/schemas/PlatformsDetected"},"events_detected":{"$ref":"#/components/schemas/EventsDetected"},"issues":{"$ref":"#/components/schemas/Issues"},"created_at":{"type":"string","format":"date-time"}}},"CategoryScores":{"type":"object","properties":{"core_analytics":{"type":"number"},"advertising_platforms":{"type":"number"},"conversion_tracking":{"type":"number"},"event_quality":{"type":"number"},"data_quality":{"type":"number"}}},"PlatformsDetected":{"type":"object","properties":{"ga4":{"type":"boolean"},"facebook_pixel":{"type":"boolean"},"google_ads":{"type":"boolean"},"tiktok":{"type":"boolean"},"linkedin":{"type":"boolean"},"other":{"type":"array","items":{"type":"string"}}}},"EventsDetected":{"type":"object","properties":{"purchase":{"type":"boolean"},"add_to_cart":{"type":"boolean"},"begin_checkout":{"type":"boolean"},"view_item":{"type":"boolean"},"lead":{"type":"boolean"},"form_submission":{"type":"boolean"},"meeting_booking":{"type":"boolean"},"content_download":{"type":"boolean"},"custom_events":{"type":"array","items":{"type":"string"}}}},"Issues":{"type":"object","properties":{"critical":{"type":"array","items":{"$ref":"#/components/schemas/IssueDetail"}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/IssueDetail"}},"passed":{"type":"array","items":{"type":"string"}}}},"IssueDetail":{"type":"object","properties":{"category":{"type":"string"},"severity":{"type":"string","enum":["critical","warning"]},"message":{"type":"string"},"recommendation":{"type":"string"},"workspace_impact":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}