Spaces:
Sleeping
Sleeping
| openapi: 3.1.0 | |
| info: | |
| # Do not change the title, if the title changes, the import paths will be broken | |
| title: Api | |
| version: 0.1.0 | |
| description: Guardian Agent API — dark pattern detection and checkout protection | |
| servers: | |
| - url: /api | |
| description: Base API path | |
| tags: | |
| - name: health | |
| description: Health operations | |
| - name: analysis | |
| description: Dark pattern analysis | |
| - name: trust | |
| description: Site trust ratings | |
| - name: reports | |
| description: Detection reports and history | |
| - name: stats | |
| description: Usage statistics and summaries | |
| paths: | |
| /healthz: | |
| get: | |
| operationId: healthCheck | |
| tags: [health] | |
| summary: Health check | |
| description: Returns server health status | |
| responses: | |
| "200": | |
| description: Healthy | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/HealthStatus" | |
| /analysis/detect: | |
| post: | |
| operationId: detectDarkPatterns | |
| tags: [analysis] | |
| summary: Detect dark patterns on a page | |
| description: Analyzes page content for dark patterns using AI classification | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/DetectDarkPatternsBody" | |
| responses: | |
| "200": | |
| description: Detection result | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/DarkPatternReport" | |
| "400": | |
| description: Invalid request | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /analysis/classify-upsell: | |
| post: | |
| operationId: classifyUpsell | |
| tags: [analysis] | |
| summary: Classify an upsell page type | |
| description: Identifies what type of upsell/add-on screen is being shown | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ClassifyUpsellBody" | |
| responses: | |
| "200": | |
| description: Upsell classification result | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/UpsellClassification" | |
| "400": | |
| description: Invalid request | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /trust: | |
| get: | |
| operationId: listTrustRatings | |
| tags: [trust] | |
| summary: List all site trust ratings | |
| description: Returns trust ratings for all tracked domains | |
| responses: | |
| "200": | |
| description: List of trust ratings | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| $ref: "#/components/schemas/TrustRating" | |
| /trust/{domain}: | |
| get: | |
| operationId: getTrustRating | |
| tags: [trust] | |
| summary: Get trust rating for a domain | |
| description: Returns the trust rating and history for a specific domain | |
| parameters: | |
| - name: domain | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| responses: | |
| "200": | |
| description: Trust rating | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/TrustRating" | |
| "404": | |
| description: Domain not found | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| put: | |
| operationId: upsertTrustRating | |
| tags: [trust] | |
| summary: Create or update trust rating for a domain | |
| description: Updates the trust rating after a checkout interaction | |
| parameters: | |
| - name: domain | |
| in: path | |
| required: true | |
| schema: | |
| type: string | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/UpsertTrustRatingBody" | |
| responses: | |
| "200": | |
| description: Updated trust rating | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/TrustRating" | |
| "400": | |
| description: Invalid request | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /reports: | |
| get: | |
| operationId: listReports | |
| tags: [reports] | |
| summary: List detection reports | |
| description: Returns recent dark pattern detection reports | |
| parameters: | |
| - name: domain | |
| in: query | |
| required: false | |
| schema: | |
| type: ["string", "null"] | |
| - name: limit | |
| in: query | |
| required: false | |
| schema: | |
| type: ["integer", "null"] | |
| responses: | |
| "200": | |
| description: List of reports | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| $ref: "#/components/schemas/DetectionReport" | |
| post: | |
| operationId: createReport | |
| tags: [reports] | |
| summary: Save a detection report | |
| description: Stores a dark pattern detection report for a session | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/CreateReportBody" | |
| responses: | |
| "201": | |
| description: Report created | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/DetectionReport" | |
| "400": | |
| description: Invalid request | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /reports/{id}: | |
| get: | |
| operationId: getReport | |
| tags: [reports] | |
| summary: Get a detection report by ID | |
| parameters: | |
| - name: id | |
| in: path | |
| required: true | |
| schema: | |
| type: integer | |
| responses: | |
| "200": | |
| description: Detection report | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/DetectionReport" | |
| "404": | |
| description: Report not found | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /stats/summary: | |
| get: | |
| operationId: getStatsSummary | |
| tags: [stats] | |
| summary: Get overall statistics summary | |
| description: Returns aggregated stats — total scans, patterns detected, money saved estimates | |
| responses: | |
| "200": | |
| description: Statistics summary | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/StatsSummary" | |
| /stats/pattern-breakdown: | |
| get: | |
| operationId: getPatternBreakdown | |
| tags: [stats] | |
| summary: Get pattern detection breakdown | |
| description: Returns counts by dark pattern type across all reports | |
| responses: | |
| "200": | |
| description: Pattern breakdown | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/PatternBreakdown" | |
| /demo/scan: | |
| post: | |
| operationId: demoScan | |
| tags: [analysis] | |
| summary: All-in-one demo scan | |
| description: Detects dark patterns, saves report, and updates trust rating in one call. Perfect for live demos. | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/DemoScanBody" | |
| responses: | |
| "200": | |
| description: Scan result with saved report | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/DemoScanResult" | |
| "400": | |
| description: Invalid request | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /demo/fee-estimate: | |
| post: | |
| operationId: demoFeeEstimate | |
| tags: [analysis] | |
| summary: Estimate true final price | |
| description: Uses AI to estimate hidden fees and total true price for a given site and listing price | |
| requestBody: | |
| required: true | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/FeeEstimateBody" | |
| responses: | |
| "200": | |
| description: Fee estimate result | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/FeeEstimateResult" | |
| "400": | |
| description: Invalid request | |
| content: | |
| application/json: | |
| schema: | |
| $ref: "#/components/schemas/ErrorResponse" | |
| /stats/top-offenders: | |
| get: | |
| operationId: getTopOffenders | |
| tags: [stats] | |
| summary: Get top offending domains | |
| description: Returns the domains with the most detected dark patterns | |
| parameters: | |
| - name: limit | |
| in: query | |
| required: false | |
| schema: | |
| type: ["integer", "null"] | |
| responses: | |
| "200": | |
| description: Top offending domains | |
| content: | |
| application/json: | |
| schema: | |
| type: array | |
| items: | |
| $ref: "#/components/schemas/DomainOffenderSummary" | |
| components: | |
| schemas: | |
| HealthStatus: | |
| type: object | |
| properties: | |
| status: | |
| type: string | |
| required: | |
| - status | |
| ErrorResponse: | |
| type: object | |
| properties: | |
| error: | |
| type: string | |
| required: | |
| - error | |
| DetectDarkPatternsBody: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| description: The website domain being analyzed | |
| pageText: | |
| type: string | |
| description: Extracted text content from the page | |
| timerElements: | |
| type: array | |
| items: | |
| type: string | |
| description: Text from countdown timer elements found on the page | |
| stockAlerts: | |
| type: array | |
| items: | |
| type: string | |
| description: Text from stock/scarcity alert elements | |
| buttonLabels: | |
| type: array | |
| items: | |
| type: string | |
| description: Text from all buttons on the page | |
| formFields: | |
| type: array | |
| items: | |
| $ref: "#/components/schemas/FormFieldInfo" | |
| description: Form field info including pre-checked state | |
| priceStrings: | |
| type: array | |
| items: | |
| type: string | |
| description: All price strings found on the page | |
| required: | |
| - domain | |
| - pageText | |
| FormFieldInfo: | |
| type: object | |
| properties: | |
| id: | |
| type: string | |
| label: | |
| type: string | |
| type: | |
| type: string | |
| checked: | |
| type: ["boolean", "null"] | |
| optional: | |
| type: ["boolean", "null"] | |
| required: | |
| - id | |
| - label | |
| - type | |
| DarkPatternReport: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| falseUrgency: | |
| $ref: "#/components/schemas/FalseUrgencyResult" | |
| falseScarcity: | |
| $ref: "#/components/schemas/FalseScarcityResult" | |
| confirmShaming: | |
| $ref: "#/components/schemas/ConfirmShamingResult" | |
| hiddenFees: | |
| $ref: "#/components/schemas/HiddenFeesResult" | |
| preCheckedAddOns: | |
| $ref: "#/components/schemas/PreCheckedAddOnsResult" | |
| misdirection: | |
| $ref: "#/components/schemas/MisdirectionResult" | |
| trustScore: | |
| type: integer | |
| description: Trust score 0-100 | |
| summary: | |
| type: string | |
| description: Human-readable summary of findings | |
| required: | |
| - domain | |
| - falseUrgency | |
| - falseScarcity | |
| - confirmShaming | |
| - hiddenFees | |
| - preCheckedAddOns | |
| - misdirection | |
| - trustScore | |
| - summary | |
| FalseUrgencyResult: | |
| type: object | |
| properties: | |
| detected: | |
| type: boolean | |
| evidence: | |
| type: string | |
| isTimerFake: | |
| type: ["boolean", "null"] | |
| required: | |
| - detected | |
| - evidence | |
| FalseScarcityResult: | |
| type: object | |
| properties: | |
| detected: | |
| type: boolean | |
| evidence: | |
| type: string | |
| required: | |
| - detected | |
| - evidence | |
| ConfirmShamingResult: | |
| type: object | |
| properties: | |
| detected: | |
| type: boolean | |
| shamingText: | |
| type: string | |
| rewrittenText: | |
| type: string | |
| required: | |
| - detected | |
| - shamingText | |
| - rewrittenText | |
| HiddenFeesResult: | |
| type: object | |
| properties: | |
| detected: | |
| type: boolean | |
| feeItems: | |
| type: array | |
| items: | |
| $ref: "#/components/schemas/FeeItem" | |
| totalExtra: | |
| type: ["number", "null"] | |
| required: | |
| - detected | |
| - feeItems | |
| FeeItem: | |
| type: object | |
| properties: | |
| label: | |
| type: string | |
| amount: | |
| type: number | |
| required: | |
| - label | |
| - amount | |
| PreCheckedAddOnsResult: | |
| type: object | |
| properties: | |
| detected: | |
| type: boolean | |
| fieldIds: | |
| type: array | |
| items: | |
| type: string | |
| addOnLabels: | |
| type: array | |
| items: | |
| type: string | |
| required: | |
| - detected | |
| - fieldIds | |
| - addOnLabels | |
| MisdirectionResult: | |
| type: object | |
| properties: | |
| detected: | |
| type: boolean | |
| hiddenDeclineText: | |
| type: string | |
| required: | |
| - detected | |
| - hiddenDeclineText | |
| ClassifyUpsellBody: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| pageText: | |
| type: string | |
| description: Text content of the upsell page | |
| required: | |
| - domain | |
| - pageText | |
| UpsellClassification: | |
| type: object | |
| properties: | |
| type: | |
| type: string | |
| enum: | |
| - insurance | |
| - breakfast | |
| - room_upgrade | |
| - seat_selection | |
| - newsletter | |
| - sms_alerts | |
| - warranty | |
| - refundable_rate | |
| - other | |
| confidence: | |
| type: number | |
| recommendedAction: | |
| type: string | |
| description: "Suggested action: decline, accept, or ask_user" | |
| declineButtonHint: | |
| type: string | |
| description: Text or selector hint for the decline button | |
| required: | |
| - type | |
| - confidence | |
| - recommendedAction | |
| - declineButtonHint | |
| TrustRating: | |
| type: object | |
| properties: | |
| id: | |
| type: integer | |
| domain: | |
| type: string | |
| score: | |
| type: integer | |
| description: Trust score 0-100 | |
| tier: | |
| type: string | |
| enum: [gold, clean, neutral, suspicious, high_manipulation] | |
| totalScans: | |
| type: integer | |
| patternsDetectedCount: | |
| type: integer | |
| hiddenFeesCount: | |
| type: integer | |
| lastScannedAt: | |
| type: ["string", "null"] | |
| createdAt: | |
| type: string | |
| updatedAt: | |
| type: string | |
| required: | |
| - id | |
| - domain | |
| - score | |
| - tier | |
| - totalScans | |
| - patternsDetectedCount | |
| - hiddenFeesCount | |
| - createdAt | |
| - updatedAt | |
| UpsertTrustRatingBody: | |
| type: object | |
| properties: | |
| scoreDelta: | |
| type: integer | |
| description: Amount to adjust the score (positive or negative) | |
| patternsFound: | |
| type: integer | |
| hiddenFeesFound: | |
| type: integer | |
| required: | |
| - scoreDelta | |
| - patternsFound | |
| - hiddenFeesFound | |
| DetectionReport: | |
| type: object | |
| properties: | |
| id: | |
| type: integer | |
| domain: | |
| type: string | |
| url: | |
| type: string | |
| trustScore: | |
| type: integer | |
| falseUrgencyDetected: | |
| type: boolean | |
| falseScarcityDetected: | |
| type: boolean | |
| confirmShamingDetected: | |
| type: boolean | |
| hiddenFeesDetected: | |
| type: boolean | |
| preCheckedAddOnsDetected: | |
| type: boolean | |
| misdirectionDetected: | |
| type: boolean | |
| totalPatternsDetected: | |
| type: integer | |
| hiddenFeesTotal: | |
| type: ["number", "null"] | |
| summary: | |
| type: string | |
| createdAt: | |
| type: string | |
| required: | |
| - id | |
| - domain | |
| - url | |
| - trustScore | |
| - falseUrgencyDetected | |
| - falseScarcityDetected | |
| - confirmShamingDetected | |
| - hiddenFeesDetected | |
| - preCheckedAddOnsDetected | |
| - misdirectionDetected | |
| - totalPatternsDetected | |
| - summary | |
| - createdAt | |
| CreateReportBody: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| url: | |
| type: string | |
| trustScore: | |
| type: integer | |
| falseUrgencyDetected: | |
| type: boolean | |
| falseScarcityDetected: | |
| type: boolean | |
| confirmShamingDetected: | |
| type: boolean | |
| hiddenFeesDetected: | |
| type: boolean | |
| preCheckedAddOnsDetected: | |
| type: boolean | |
| misdirectionDetected: | |
| type: boolean | |
| totalPatternsDetected: | |
| type: integer | |
| hiddenFeesTotal: | |
| type: ["number", "null"] | |
| summary: | |
| type: string | |
| required: | |
| - domain | |
| - url | |
| - trustScore | |
| - falseUrgencyDetected | |
| - falseScarcityDetected | |
| - confirmShamingDetected | |
| - hiddenFeesDetected | |
| - preCheckedAddOnsDetected | |
| - misdirectionDetected | |
| - totalPatternsDetected | |
| - summary | |
| StatsSummary: | |
| type: object | |
| properties: | |
| totalScans: | |
| type: integer | |
| totalPatternsDetected: | |
| type: integer | |
| totalHiddenFeesBlocked: | |
| type: number | |
| description: Estimated total money saved in dollars | |
| totalDomainsTracked: | |
| type: integer | |
| totalReportsLast30Days: | |
| type: integer | |
| avgTrustScore: | |
| type: number | |
| goldTierDomains: | |
| type: integer | |
| highManipulationDomains: | |
| type: integer | |
| required: | |
| - totalScans | |
| - totalPatternsDetected | |
| - totalHiddenFeesBlocked | |
| - totalDomainsTracked | |
| - totalReportsLast30Days | |
| - avgTrustScore | |
| - goldTierDomains | |
| - highManipulationDomains | |
| PatternBreakdown: | |
| type: object | |
| properties: | |
| falseUrgency: | |
| type: integer | |
| falseScarcity: | |
| type: integer | |
| confirmShaming: | |
| type: integer | |
| hiddenFees: | |
| type: integer | |
| preCheckedAddOns: | |
| type: integer | |
| misdirection: | |
| type: integer | |
| required: | |
| - falseUrgency | |
| - falseScarcity | |
| - confirmShaming | |
| - hiddenFees | |
| - preCheckedAddOns | |
| - misdirection | |
| DomainOffenderSummary: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| totalPatternsDetected: | |
| type: integer | |
| trustScore: | |
| type: integer | |
| tier: | |
| type: string | |
| totalScans: | |
| type: integer | |
| required: | |
| - domain | |
| - totalPatternsDetected | |
| - trustScore | |
| - tier | |
| - totalScans | |
| DemoScanBody: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| url: | |
| type: string | |
| pageText: | |
| type: string | |
| timerElements: | |
| type: array | |
| items: | |
| type: string | |
| stockAlerts: | |
| type: array | |
| items: | |
| type: string | |
| buttonLabels: | |
| type: array | |
| items: | |
| type: string | |
| priceStrings: | |
| type: array | |
| items: | |
| type: string | |
| scenarioName: | |
| type: ["string", "null"] | |
| description: Name of the preset scenario being run | |
| required: | |
| - domain | |
| - url | |
| - pageText | |
| DemoScanResult: | |
| type: object | |
| properties: | |
| report: | |
| $ref: "#/components/schemas/DetectionReport" | |
| darkPatternReport: | |
| $ref: "#/components/schemas/DarkPatternReport" | |
| trustRating: | |
| $ref: "#/components/schemas/TrustRating" | |
| required: | |
| - report | |
| - darkPatternReport | |
| - trustRating | |
| FeeEstimateBody: | |
| type: object | |
| properties: | |
| domain: | |
| type: string | |
| merchantType: | |
| type: string | |
| description: "Type of merchant: hotel, airline, ecommerce, vacation_rental, car_rental" | |
| listedPrice: | |
| type: number | |
| currency: | |
| type: string | |
| default: USD | |
| itemDescription: | |
| type: ["string", "null"] | |
| required: | |
| - domain | |
| - merchantType | |
| - listedPrice | |
| FeeEstimateResult: | |
| type: object | |
| properties: | |
| listedPrice: | |
| type: number | |
| estimatedTotal: | |
| type: number | |
| savingsOpportunity: | |
| type: number | |
| feeBreakdown: | |
| type: array | |
| items: | |
| $ref: "#/components/schemas/FeeItem" | |
| confidence: | |
| type: string | |
| enum: [high, medium, low] | |
| warningLevel: | |
| type: string | |
| enum: [green, orange, red] | |
| explanation: | |
| type: string | |
| required: | |
| - listedPrice | |
| - estimatedTotal | |
| - savingsOpportunity | |
| - feeBreakdown | |
| - confidence | |
| - warningLevel | |
| - explanation | |