{
  "openapi": "3.1.0",
  "info": {
    "title": "Tenmomo Public API",
    "description": "Public API for accessing cashback store data, deals, and coupon codes from Tenmomo. Designed for AI agents, shopping assistants, and developers. No authentication required. Rate limited to 60 requests per minute.",
    "version": "1.0.0",
    "contact": {
      "name": "Tenmomo",
      "url": "https://tenmomo.com"
    }
  },
  "servers": [
    {
      "url": "https://tenmomo.com/api/v1",
      "description": "Production"
    }
  ],
  "paths": {
    "/stores": {
      "get": {
        "operationId": "listStores",
        "summary": "Search and list cashback stores",
        "description": "Returns a paginated list of active stores with cashback rates. Use the `q` parameter to search by store name.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search stores by name",
            "schema": { "type": "string" }
          },
          {
            "name": "category_id",
            "in": "query",
            "description": "Filter by category ID",
            "schema": { "type": "integer" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (max 50)",
            "schema": { "type": "integer", "default": 20, "maximum": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of stores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/StoreSummary" }
                    },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/stores/{id}": {
      "get": {
        "operationId": "getStore",
        "summary": "Get store details",
        "description": "Returns full details for a store including all cashback tiers, active coupons, and categories.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Store ID",
            "schema": { "type": "integer" }
          }
        ],
        "responses": {
          "200": {
            "description": "Store details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/StoreDetail" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Store not found"
          }
        }
      }
    },
    "/deals": {
      "get": {
        "operationId": "listDeals",
        "summary": "Find active deals and coupon codes",
        "description": "Returns a paginated list of active coupon codes and deals. Filter by store or search by keyword.",
        "parameters": [
          {
            "name": "store_id",
            "in": "query",
            "description": "Filter deals by store ID",
            "schema": { "type": "integer" }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search deals by keyword",
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (max 50)",
            "schema": { "type": "integer", "default": 20, "maximum": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of deals",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Deal" }
                    },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories": {
      "get": {
        "operationId": "listCategories",
        "summary": "List shopping categories",
        "description": "Returns all categories with their store counts.",
        "responses": {
          "200": {
            "description": "List of categories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Category" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/categories/{id}/stores": {
      "get": {
        "operationId": "listCategoryStores",
        "summary": "Get stores in a category",
        "description": "Returns cashback stores belonging to a specific category.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Category ID",
            "schema": { "type": "integer" }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Results per page (max 100)",
            "schema": { "type": "integer", "default": 30, "maximum": 100 }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": {
            "description": "List of stores in category",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/StoreSummary" }
                    },
                    "category": { "type": "string" },
                    "pagination": { "$ref": "#/components/schemas/Pagination" }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Category not found"
          }
        }
      }
    },
    "/activate": {
      "post": {
        "operationId": "activateCashback",
        "summary": "Generate a personalized cashback activation link",
        "description": "Creates a tracked activation URL attributed to the authenticated user. The returned URL must be opened in a browser to set affiliate tracking cookies before shopping. Requires a Tenmomo API key (sk-tm-...).",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["store_id"],
                "properties": {
                  "store_id": { "type": "integer", "description": "Store ID to activate cashback for" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Activation link generated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ActivationResult" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" },
          "404": { "description": "Store not found" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Tenmomo API key (sk-tm-...). Get one at https://tenmomo.com/dashboard#ai-credits"
      }
    },
    "schemas": {
      "ActivationResult": {
        "type": "object",
        "properties": {
          "activation_url": { "type": "string", "format": "uri", "description": "Open this URL in a browser to activate cashback tracking" },
          "click_id": { "type": "string", "description": "Unique click tracking ID" },
          "store": { "type": "string", "description": "Store name" },
          "store_id": { "type": "integer" },
          "cashback": { "type": "string", "description": "Cashback rate" },
          "instructions": { "type": "string" }
        }
      },
      "StoreSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "integer", "description": "Store ID" },
          "name": { "type": "string", "description": "Store name" },
          "website": { "type": "string", "format": "uri", "description": "Store website URL" },
          "cashback": { "type": "string", "description": "Cashback rate (e.g. '5.00% cashback')" },
          "coupon_count": { "type": "integer", "description": "Number of active coupons" },
          "activation_url": { "type": "string", "format": "uri", "description": "Click this URL to activate cashback tracking before shopping" }
        }
      },
      "StoreDetail": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "description": { "type": "string", "nullable": true },
          "website": { "type": "string", "format": "uri" },
          "network": { "type": "string", "description": "Affiliate network (cj, awin, impact)" },
          "cookie_duration_days": { "type": "integer", "nullable": true },
          "activation_url": { "type": "string", "format": "uri" },
          "cashback_tiers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": { "type": "string" },
                "rate": { "type": "string" },
                "is_default": { "type": "boolean" }
              }
            }
          },
          "coupons": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Deal" }
          },
          "categories": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "Deal": {
        "type": "object",
        "properties": {
          "store": { "type": "string", "description": "Store name" },
          "store_id": { "type": "integer" },
          "title": { "type": "string", "description": "Deal title" },
          "code": { "type": "string", "nullable": true, "description": "Coupon code (if applicable)" },
          "discount": { "type": "string", "description": "Discount description" },
          "expires": { "type": "string", "format": "date", "nullable": true },
          "activation_url": { "type": "string", "format": "uri" }
        }
      },
      "Category": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "store_count": { "type": "integer" }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "limit": { "type": "integer" },
          "offset": { "type": "integer" },
          "has_more": { "type": "boolean" }
        }
      }
    }
  }
}