{
 "openapi": "3.1.0",
 "info": {
  "title": "Perq API",
  "version": "1.0.0",
  "description": "Free AI credits, startup programs and perks — with proof on every listing. Read-only, no key, no signup. Every offer quotes the vendor's own page (source_url, source_snippet) with a last_verified timestamp; show those to users. Remote MCP server with the same data: https://perq.sh/mcp (Streamable HTTP, no auth). Docs: https://perq.sh/agents.",
  "contact": {
   "name": "Avatar 8",
   "email": "ops@avatar33.com",
   "url": "https://perq.sh/about"
  }
 },
 "servers": [
  {
   "url": "https://perq.sh"
  }
 ],
 "externalDocs": {
  "url": "https://perq.sh/agents",
  "description": "Agent docs, MCP setup, examples"
 },
 "paths": {
  "/api/search": {
   "get": {
    "operationId": "searchOffers",
    "summary": "Search verified free credits and perks",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Plain-language need, e.g. \"free speech to text credits\". Empty = all."
     },
     {
      "name": "category",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Comma list of category slugs: agents-automation, cloud-gpu, llm-api, dev-tools, observability, database-backend, voice-audio, perk-marketplace, vector-db, image-video, productivity, accelerator"
     },
     {
      "name": "type",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Comma list of offer-type slugs: free-tier, startup-program, signup-credit, student-education, marketplace-perk, accelerator-perk, promo-code"
     },
     {
      "name": "sort",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "relevance",
        "popular",
        "votes",
        "newest",
        "verified",
        "value",
        "az"
       ]
      }
     },
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "live",
        "closed",
        "all"
       ],
       "default": "live"
      }
     },
     {
      "name": "audience",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "startup",
        "student",
        "anyone",
        "members"
       ]
      }
     },
     {
      "name": "student",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "no_application",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "min_value",
      "in": "query",
      "schema": {
       "type": "number"
      },
      "description": "Minimum stated one-time USD credit."
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "query": {
           "type": "string"
          },
          "total_matches": {
           "type": "integer"
          },
          "count": {
           "type": "integer"
          },
          "results": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "vendor": {
              "type": "string"
             },
             "category": {
              "type": "string",
              "enum": [
               "agents/automation",
               "cloud/GPU",
               "LLM API",
               "dev tools",
               "observability",
               "database/backend",
               "voice/audio",
               "perk marketplace",
               "vector DB",
               "image/video",
               "productivity",
               "accelerator"
              ]
             },
             "offer_type": {
              "type": "string",
              "enum": [
               "free tier",
               "startup program",
               "signup credit",
               "student/education",
               "marketplace perk",
               "accelerator perk",
               "promo code"
              ]
             },
             "status": {
              "type": "string",
              "enum": [
               "live",
               "closed"
              ]
             },
             "closed_on": {
              "type": [
               "string",
               "null"
              ],
              "format": "date"
             },
             "credit_value": {
              "type": "string",
              "description": "Vendor wording, verbatim."
             },
             "eligibility": {
              "type": [
               "string",
               "null"
              ]
             },
             "how_to_claim": {
              "type": [
               "string",
               "null"
              ]
             },
             "code": {
              "type": [
               "string",
               "null"
              ]
             },
             "claim_url": {
              "type": "string",
              "format": "uri"
             },
             "source_url": {
              "type": "string",
              "format": "uri"
             },
             "source_snippet": {
              "type": "string",
              "description": "Verbatim quote from source_url."
             },
             "last_verified": {
              "type": "string",
              "format": "date-time"
             },
             "first_seen": {
              "type": [
               "string",
               "null"
              ],
              "format": "date"
             },
             "no_application": {
              "type": "boolean"
             },
             "value_usd": {
              "type": [
               "number",
               "null"
              ],
              "description": "Explicit one-time USD amount the vendor states, else null."
             },
             "audience": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "perq_url": {
              "type": "string",
              "format": "uri"
             },
             "claim_redirect_url": {
              "type": "string",
              "format": "uri"
             },
             "claims": {
              "type": [
               "integer",
               "null"
              ]
             },
             "claims_7d": {
              "type": [
               "integer",
               "null"
              ]
             },
             "votes": {
              "type": [
               "integer",
               "null"
              ]
             }
            },
            "required": [
             "id",
             "vendor",
             "category",
             "offer_type",
             "status",
             "credit_value",
             "source_url",
             "last_verified"
            ]
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid parameters",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/offers/{id}": {
   "get": {
    "operationId": "getOffer",
    "summary": "One offer by id",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "aws-activate-credits"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "string"
          },
          "vendor": {
           "type": "string"
          },
          "category": {
           "type": "string",
           "enum": [
            "agents/automation",
            "cloud/GPU",
            "LLM API",
            "dev tools",
            "observability",
            "database/backend",
            "voice/audio",
            "perk marketplace",
            "vector DB",
            "image/video",
            "productivity",
            "accelerator"
           ]
          },
          "offer_type": {
           "type": "string",
           "enum": [
            "free tier",
            "startup program",
            "signup credit",
            "student/education",
            "marketplace perk",
            "accelerator perk",
            "promo code"
           ]
          },
          "status": {
           "type": "string",
           "enum": [
            "live",
            "closed"
           ]
          },
          "closed_on": {
           "type": [
            "string",
            "null"
           ],
           "format": "date"
          },
          "credit_value": {
           "type": "string",
           "description": "Vendor wording, verbatim."
          },
          "eligibility": {
           "type": [
            "string",
            "null"
           ]
          },
          "how_to_claim": {
           "type": [
            "string",
            "null"
           ]
          },
          "code": {
           "type": [
            "string",
            "null"
           ]
          },
          "claim_url": {
           "type": "string",
           "format": "uri"
          },
          "source_url": {
           "type": "string",
           "format": "uri"
          },
          "source_snippet": {
           "type": "string",
           "description": "Verbatim quote from source_url."
          },
          "last_verified": {
           "type": "string",
           "format": "date-time"
          },
          "first_seen": {
           "type": [
            "string",
            "null"
           ],
           "format": "date"
          },
          "no_application": {
           "type": "boolean"
          },
          "value_usd": {
           "type": [
            "number",
            "null"
           ],
           "description": "Explicit one-time USD amount the vendor states, else null."
          },
          "audience": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "perq_url": {
           "type": "string",
           "format": "uri"
          },
          "claim_redirect_url": {
           "type": "string",
           "format": "uri"
          },
          "claims": {
           "type": [
            "integer",
            "null"
           ]
          },
          "claims_7d": {
           "type": [
            "integer",
            "null"
           ]
          },
          "votes": {
           "type": [
            "integer",
            "null"
           ]
          }
         },
         "required": [
          "id",
          "vendor",
          "category",
          "offer_type",
          "status",
          "credit_value",
          "source_url",
          "last_verified"
         ]
        }
       }
      }
     },
     "404": {
      "description": "Unknown id",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/offers.json": {
   "get": {
    "operationId": "listOffers",
    "summary": "Full public dataset",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "offers": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "string"
             },
             "vendor": {
              "type": "string"
             },
             "category": {
              "type": "string",
              "enum": [
               "agents/automation",
               "cloud/GPU",
               "LLM API",
               "dev tools",
               "observability",
               "database/backend",
               "voice/audio",
               "perk marketplace",
               "vector DB",
               "image/video",
               "productivity",
               "accelerator"
              ]
             },
             "offer_type": {
              "type": "string",
              "enum": [
               "free tier",
               "startup program",
               "signup credit",
               "student/education",
               "marketplace perk",
               "accelerator perk",
               "promo code"
              ]
             },
             "status": {
              "type": "string",
              "enum": [
               "live",
               "closed"
              ]
             },
             "closed_on": {
              "type": [
               "string",
               "null"
              ],
              "format": "date"
             },
             "credit_value": {
              "type": "string",
              "description": "Vendor wording, verbatim."
             },
             "eligibility": {
              "type": [
               "string",
               "null"
              ]
             },
             "how_to_claim": {
              "type": [
               "string",
               "null"
              ]
             },
             "code": {
              "type": [
               "string",
               "null"
              ]
             },
             "claim_url": {
              "type": "string",
              "format": "uri"
             },
             "source_url": {
              "type": "string",
              "format": "uri"
             },
             "source_snippet": {
              "type": "string",
              "description": "Verbatim quote from source_url."
             },
             "last_verified": {
              "type": "string",
              "format": "date-time"
             },
             "first_seen": {
              "type": [
               "string",
               "null"
              ],
              "format": "date"
             },
             "no_application": {
              "type": "boolean"
             },
             "value_usd": {
              "type": [
               "number",
               "null"
              ],
              "description": "Explicit one-time USD amount the vendor states, else null."
             },
             "audience": {
              "type": "array",
              "items": {
               "type": "string"
              }
             },
             "perq_url": {
              "type": "string",
              "format": "uri"
             },
             "claim_redirect_url": {
              "type": "string",
              "format": "uri"
             },
             "claims": {
              "type": [
               "integer",
               "null"
              ]
             },
             "claims_7d": {
              "type": [
               "integer",
               "null"
              ]
             },
             "votes": {
              "type": [
               "integer",
               "null"
              ]
             }
            },
            "required": [
             "id",
             "vendor",
             "category",
             "offer_type",
             "status",
             "credit_value",
             "source_url",
             "last_verified"
            ]
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/packs.json": {
   "get": {
    "operationId": "listPacks",
    "summary": "Curated packs with total breakdowns",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/counts": {
   "get": {
    "operationId": "getCounts",
    "summary": "Live claim and vote counts per offer",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "503": {
      "description": "Counts unavailable",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/state-of-free-ai-credits.json": {
   "get": {
    "operationId": "getReport",
    "summary": "State of free AI credits: headline numbers, methodology and per-offer rows",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/subscribe": {
   "get": {
    "operationId": "subscribeDocs",
    "summary": "How to subscribe (machine-readable)",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   },
   "post": {
    "operationId": "subscribe",
    "summary": "Get new offers about 24 hours before they are public",
    "description": "Send either email (double opt-in confirmation email) or webhook_url (signed JSON POSTs; secret returned once).",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "email": {
          "type": "string",
          "format": "email"
         },
         "webhook_url": {
          "type": "string",
          "format": "uri"
         },
         "topics": {
          "type": "array",
          "items": {
           "type": "string",
           "enum": [
            "llm-api",
            "gpu",
            "voice",
            "startup-programs",
            "student",
            "agents",
            "dev-tools"
           ]
          }
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Webhook registered",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "secret": {
           "type": "string"
          },
          "feed_json": {
           "type": "string"
          },
          "feed_rss": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "202": {
      "description": "Confirmation email sent",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "status": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid body",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Rate limited",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/unsubscribe": {
   "post": {
    "operationId": "unsubscribe",
    "summary": "Stop deliveries",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "token": {
          "type": "string"
         }
        },
        "required": [
         "token"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/early/{feed_token}.json": {
   "get": {
    "operationId": "earlyFeed",
    "summary": "Private early-access feed for a subscriber",
    "parameters": [
     {
      "name": "feed_token",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "message": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/go/{id}": {
   "get": {
    "operationId": "claimRedirect",
    "summary": "Counted claim link: 302 to the vendor claim_url",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "via",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "agent"
       ]
      }
     }
    ],
    "responses": {
     "302": {
      "description": "Redirect to the vendor"
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Offer": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "vendor": {
      "type": "string"
     },
     "category": {
      "type": "string",
      "enum": [
       "agents/automation",
       "cloud/GPU",
       "LLM API",
       "dev tools",
       "observability",
       "database/backend",
       "voice/audio",
       "perk marketplace",
       "vector DB",
       "image/video",
       "productivity",
       "accelerator"
      ]
     },
     "offer_type": {
      "type": "string",
      "enum": [
       "free tier",
       "startup program",
       "signup credit",
       "student/education",
       "marketplace perk",
       "accelerator perk",
       "promo code"
      ]
     },
     "status": {
      "type": "string",
      "enum": [
       "live",
       "closed"
      ]
     },
     "closed_on": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "credit_value": {
      "type": "string",
      "description": "Vendor wording, verbatim."
     },
     "eligibility": {
      "type": [
       "string",
       "null"
      ]
     },
     "how_to_claim": {
      "type": [
       "string",
       "null"
      ]
     },
     "code": {
      "type": [
       "string",
       "null"
      ]
     },
     "claim_url": {
      "type": "string",
      "format": "uri"
     },
     "source_url": {
      "type": "string",
      "format": "uri"
     },
     "source_snippet": {
      "type": "string",
      "description": "Verbatim quote from source_url."
     },
     "last_verified": {
      "type": "string",
      "format": "date-time"
     },
     "first_seen": {
      "type": [
       "string",
       "null"
      ],
      "format": "date"
     },
     "no_application": {
      "type": "boolean"
     },
     "value_usd": {
      "type": [
       "number",
       "null"
      ],
      "description": "Explicit one-time USD amount the vendor states, else null."
     },
     "audience": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "perq_url": {
      "type": "string",
      "format": "uri"
     },
     "claim_redirect_url": {
      "type": "string",
      "format": "uri"
     },
     "claims": {
      "type": [
       "integer",
       "null"
      ]
     },
     "claims_7d": {
      "type": [
       "integer",
       "null"
      ]
     },
     "votes": {
      "type": [
       "integer",
       "null"
      ]
     }
    },
    "required": [
     "id",
     "vendor",
     "category",
     "offer_type",
     "status",
     "credit_value",
     "source_url",
     "last_verified"
    ]
   },
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "message": {
      "type": "string"
     }
    }
   }
  }
 }
}