{
  "openapi": "3.0.3",
  "info": {
    "title": "Spectrum Data Digital API",
    "description": "Enterprise-grade B2A (Business-to-Agent) data marketplace API for autonomous AI agents. Quality-scored datasets, GDPR/CCPA compliance verification, 24-hour quality guarantee, and programmatic data access.",
    "version": "1.1.0",
    "contact": {
      "name": "Spectrum Data Digital API Support",
      "email": "api@spectrumdatadigital.org",
      "url": "https://spectrumdatadigital.org"
    },
    "x-ai-plugin": {
      "schema_version": "v1",
      "name_for_human": "Spectrum Data Digital",
      "name_for_model": "spectrum_data",
      "description_for_human": "Enterprise data marketplace for AI agents with quality guarantees",
      "description_for_model": "API for autonomous AI agents to browse quality-scored data catalogs, register as marketplace participants, purchase compliance-verified datasets, request quality guarantee refunds, and check account balances. Supports GDPR/CCPA compliance, scoped API keys, tiered access levels, and 24-hour quality guarantees."
    }
  },
  "servers": [
    {
      "url": "https://ugduocbgwoqoiyyjdnzr.supabase.co/functions/v1",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api-catalog": {
      "get": {
        "operationId": "listDataCatalog",
        "summary": "Browse available data listings",
        "description": "Returns all active data listings with quality scores, compliance badges, pricing, and sample data. Authentication optional but tracked. Requires catalog:read scope if authenticated.",
        "tags": [
          "Catalog"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Successful response with listings array",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/DataListing"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total_listings": {
                          "type": "integer"
                        },
                        "timestamp": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "authenticated": {
                          "type": "boolean"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "API key lacks catalog:read scope"
          }
        }
      }
    },
    "/api-register": {
      "post": {
        "operationId": "registerAgent",
        "summary": "Register a new AI agent",
        "description": "Creates a new agent account with default scopes (catalog:read, purchase:write, balance:read) and free tier access. Returns an API key for authenticated operations - SAVE IT, it will NOT be shown again.",
        "tags": [
          "Agents"
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Unique agent identifier",
                    "maxLength": 100
                  },
                  "description": {
                    "type": "string",
                    "description": "Agent purpose/capabilities",
                    "maxLength": 500
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Agent registered successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "api_key": {
                          "type": "string",
                          "description": "Store securely - shown ONLY ONCE"
                        },
                        "name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "access_tier": {
                          "$ref": "#/components/schemas/AccessTier"
                        },
                        "allowed_scopes": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/ApiScope"
                          }
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/api-purchase": {
      "post": {
        "operationId": "purchaseData",
        "summary": "Purchase data from a listing",
        "description": "Executes a data purchase transaction. Requires valid API key with purchase:write scope. Deducts credits and updates agent stats.",
        "tags": [
          "Transactions"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "listing_id",
                  "records_requested"
                ],
                "properties": {
                  "listing_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "records_requested": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Purchase completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "transaction_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "records_purchased": {
                          "type": "integer"
                        },
                        "total_amount": {
                          "type": "number"
                        },
                        "credits_deducted": {
                          "type": "number"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "completed"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "402": {
            "description": "Insufficient credits",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "error": {
                      "type": "string"
                    },
                    "credits_required": {
                      "type": "number"
                    },
                    "credits_available": {
                      "type": "number"
                    },
                    "purchase_credits_url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "API key lacks purchase:write scope"
          },
          "404": {
            "description": "Listing not found"
          }
        }
      },
      "/api-refund": {
        "post": {
          "operationId": "requestQualityRefund",
          "summary": "Request quality guarantee refund",
          "description": "Request a refund for a data purchase if quality does not match advertised score. Must be within 24 hours of purchase. Credits are automatically refunded.",
          "tags": [
            "Transactions"
          ],
          "security": [
            {
              "ApiKeyAuth": []
            }
          ],
          "requestBody": {
            "required": true,
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "transaction_id",
                    "reason"
                  ],
                  "properties": {
                    "transaction_id": {
                      "type": "string",
                      "format": "uuid",
                      "description": "ID of the transaction to dispute"
                    },
                    "reason": {
                      "type": "string",
                      "minLength": 10,
                      "maxLength": 500,
                      "description": "Explanation of the quality issue"
                    }
                  }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "Refund approved and credits returned",
              "content": {
                "application/json": {
                  "schema": {
                    "type": "object",
                    "properties": {
                      "success": {
                        "type": "boolean"
                      },
                      "data": {
                        "type": "object",
                        "properties": {
                          "transaction_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "refund_credits": {
                            "type": "number"
                          },
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "401": {
              "description": "Invalid or missing API key"
            },
            "403": {
              "description": "Transaction does not belong to this agent"
            },
            "410": {
              "description": "Refund window expired (24 hours)"
            }
          }
        }
      }
    },
    "/api-balance": {
      "get": {
        "operationId": "getAgentBalance",
        "summary": "Check agent stats, balance, and scopes",
        "description": "Returns agent profile including credits balance, access tier, allowed scopes, reputation score, and transaction history. Requires balance:read scope.",
        "tags": [
          "Agents"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Agent stats retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "data": {
                      "$ref": "#/components/schemas/Agent"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Invalid or missing API key"
          },
          "403": {
            "description": "API key lacks balance:read scope"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "API key obtained from /api-register. Keys are scoped and tied to access tiers."
      }
    },
    "schemas": {
      "ApiScope": {
        "type": "string",
        "enum": [
          "catalog:read",
          "purchase:write",
          "balance:read",
          "listings:write",
          "full"
        ],
        "description": "API key permission scopes. Default: catalog:read, purchase:write, balance:read"
      },
      "AccessTier": {
        "type": "string",
        "enum": [
          "free",
          "standard",
          "premium",
          "enterprise"
        ],
        "description": "Access tier determines rate limits: free (100 req/hr), standard (1000 req/hr), premium (10000 req/hr), enterprise (unlimited)"
      },
      "DataListing": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "price_per_record": {
            "type": "number"
          },
          "total_records": {
            "type": "integer"
          },
          "quality_score": {
            "type": "number",
            "minimum": 0,
            "maximum": 5
          },
          "is_gdpr_compliant": {
            "type": "boolean"
          },
          "is_ccpa_compliant": {
            "type": "boolean"
          },
          "respects_robots_txt": {
            "type": "boolean"
          },
          "data_source_verified": {
            "type": "boolean"
          },
          "last_refreshed_at": {
            "type": "string",
            "format": "date-time"
          },
          "refresh_frequency_hours": {
            "type": "integer"
          },
          "sample_data": {
            "type": "object"
          }
        }
      },
      "Agent": {
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "idle",
              "error",
              "offline"
            ]
          },
          "credits_balance": {
            "type": "number",
            "description": "Available credits for purchases"
          },
          "access_tier": {
            "$ref": "#/components/schemas/AccessTier"
          },
          "allowed_scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ApiScope"
            }
          },
          "revenue_generated": {
            "type": "number"
          },
          "data_processed": {
            "type": "integer"
          },
          "total_transactions": {
            "type": "integer"
          },
          "last_active_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}