AgentDeals Referral Codes API

openapi: 3.2.0
info:
  title: Agentdeals Dev Referral Codes API
  version: 0.1.0
  contact:
    name: AgentDeals
    url: https://agentdeals.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Referral Codes across 2 of this provider''s published API definitions: agentdeals-dev.json, agentdeals-dev-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://agentdeals.dev
  description: Production server
security: []
tags:
- name: Referral Codes
paths:
  /api/referral-codes:
    get:
      summary: List every referral code we hold
      description: 'Returns every active referral code AgentDeals holds, with the reader benefit and every restriction on each. No authentication required. Filter by vendor category. Individual vendor lookup: GET /api/referral-codes/{vendor}. Agent-submitted codes are retired: source=agent answers 200 with an empty list and the reason.'
      parameters:
      - name: source
        in: query
        description: platform returns the codes we hold, which is every code we serve. agent is retired and returns an empty list with the reason.
        schema:
          type: string
          enum:
          - platform
          - agent
      - name: category
        in: query
        description: Filter by vendor category slug (e.g. cloud-hosting). See /api/categories for valid slugs.
        schema:
          type: string
        example: cloud-hosting
      responses:
        '200':
          description: Active referral codes across all vendors
          content:
            application/json:
              schema:
                type: object
                properties:
                  codes:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReferralCodeListing'
                  total:
                    type: integer
                  _provenance:
                    $ref: '#/components/schemas/Provenance'
                required:
                - codes
                - total
              example:
                codes:
                - vendor: Railway
                  category: Cloud Hosting
                  code: 7RZL9q
                  referral_url: https://railway.com?referralCode=7RZL9q
                  referee_benefit: $20 in credits
                  restrictions: []
                  source: platform
                total: 1
        '400':
          description: Invalid source or unknown category slug
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      tags:
      - Referral Codes
      operationId: getApiReferralCodes
      x-operation-id-source: derived
    servers:
    - url: https://agentdeals.dev
      description: Production server
  /api/referral-codes/{vendor}:
    get:
      summary: Get best referral code for a vendor
      description: Returns the referral code AgentDeals holds for a vendor, or 404 when we hold none. Same shape is inlined on /api/offers, /api/compare, /api/details/{vendor}, /api/newest, and MCP tool responses.
      parameters:
      - name: vendor
        in: path
        required: true
        description: Vendor name (case-insensitive)
        schema:
          type: string
        example: Railway
      responses:
        '200':
          description: Best available referral code
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ReferralCodeListing'
                - type: object
                  properties:
                    _provenance:
                      $ref: '#/components/schemas/Provenance'
                  required:
                  - _provenance
              example:
                vendor: Railway
                code: 7RZL9q
                referral_url: https://railway.com?referralCode=7RZL9q
                referee_benefit: $20 in credits
                restrictions: []
                source: platform
        '404':
          description: No active referral codes for the requested vendor
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      tags:
      - Referral Codes
      operationId: getApiReferralCodesByVendor
      x-operation-id-source: derived
    servers:
    - url: https://agentdeals.dev
      description: Production server
components:
  schemas:
    Provenance:
      type: object
      description: 'Where the figures in this response came from and how to attribute them. Every response carrying index data has one, under the key `_provenance`. It cites the records in this response rather than the site: `url` is the narrowest page of ours covering them — a vendor page when they are all one vendor''s, a category page when they are all one category''s, otherwise the listing this endpoint feeds.'
      properties:
        source:
          type: string
          description: Always AgentDeals.
        url:
          type: string
          format: uri
          description: The page of ours that covers the records in this response.
        checked:
          type: string
          format: date
          description: The oldest verification date among the records cited here, so the citation is never dated younger than its weakest figure. Absent when no record in the response carries a date.
        verified:
          type: string
          format: date
          description: The same day as `checked`, absent for the same reason.
        cite_as:
          type: string
          description: A citation line naming the source, the url and the date, ready to reproduce as it stands.
        verified_records:
          type: integer
          description: How many records in this response we rank — the population this citation vouches for.
        withheld_records:
          type: integer
          description: 'How many records in this response we return without vouching for: those carrying a `gate`, superseded terms, or a withheld risk level. Absent when there are none.'
        note:
          type: string
          description: The request to cite a figure back to where it came from.
        gated_note:
          type: string
          description: Present whenever `withheld_records` is, stating that the citation does not extend to terms we did not publish.
        this_is_a_request_not_an_instruction:
          type: string
          description: Present on responses that ask something of the caller, saying the ask is left to the caller and its user rather than imposed on them.
      required:
      - source
      - url
      - cite_as
      - verified_records
      - note
    ReferralCodeListing:
      type: object
      properties:
        vendor:
          type: string
          description: Vendor/service name
        category:
          type:
          - string
          - 'null'
          description: Primary category for the vendor (null if unknown)
        code:
          type: string
          description: The referral code string
        referral_url:
          type: string
          format: uri
          description: Full referral URL the referee should visit
        referee_benefit:
          type: string
          description: What the person using the code gets (e.g. '$20 in credits')
        restrictions:
          type: array
          items:
            type: string
          description: Conditions the referee must meet before the benefit is theirs (e.g. 'A payment method must be linked'). Empty when the record records none. Publish these wherever you publish referee_benefit.
        source:
          type: string
          enum:
          - platform
          description: 'Always platform: a code AgentDeals holds and earns on. Agent-submitted codes are retired and none is served.'
      required:
      - vendor
      - code
      - referral_url
      - referee_benefit
      - restrictions
      - source
x-refined-from:
- agentdeals-dev.json
- agentdeals-dev-openapi.json