AgentDeals Audit Stack API

openapi: 3.2.0
info:
  title: Agentdeals Dev Audit Stack API
  version: 0.1.0
  contact:
    name: AgentDeals
    url: https://agentdeals.dev
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged Audit Stack 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: Audit Stack
paths:
  /api/audit-stack:
    get:
      summary: Audit your infrastructure stack
      description: Analyze your current services for pricing risks, cost savings, and missing capabilities. Returns per-service risk assessment, cheaper alternatives, and gap analysis.
      parameters:
      - name: services
        in: query
        required: true
        description: Comma-separated vendor names (e.g. 'Vercel,Supabase,Clerk'). An audit reports only names it matched exactly; anything else comes back as status not_found with suggestions, so that risks_found and cheaper_alternative are never computed for a product you did not name (#1269).
        schema:
          type: string
        example: Vercel,Supabase,Clerk
      responses:
        '200':
          description: Stack audit results
          content:
            application/json:
              schema:
                type: object
                properties:
                  services_analyzed:
                    type: number
                  risks_found:
                    type: number
                    description: Services carrying a published caution or risky level. A service whose level is withheld is not counted here — it is unrated, not safe (#1486).
                  savings_opportunities:
                    type: number
                  gaps:
                    type: array
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                        recommendation:
                          type: object
                          properties:
                            vendor:
                              type: string
                            tier:
                              type: string
                            description:
                              type: string
                            terms_superseded:
                              $ref: '#/components/schemas/TermsSuperseded'
                            conditions:
                              type: array
                              description: 'A list of the conditions a vendor attaches to using its free tier. Each item holds our sentence (text), the vendor''s own words (quote), the page that states them (url) and the date we read that page (read_on). An optional list rules_out names the uses the vendor excludes: "production", "commercial use" or both. Our re-reads of the vendor''s pricing page do not change this field.'
                              items:
                                type: object
                                properties:
                                  text:
                                    type: string
                                  quote:
                                    type: string
                                  url:
                                    type: string
                                    format: uri
                                  read_on:
                                    type: string
                                    format: date
                                  rules_out:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                      - production
                                      - commercial use
                                required:
                                - text
                                - quote
                                - url
                                - read_on
                  services:
                    type: array
                    items:
                      type: object
                      properties:
                        vendor:
                          type: string
                        status:
                          type: string
                          enum:
                          - found
                          - not_found
                        category:
                          type: string
                        tier:
                          type: string
                        risk_level:
                          type:
                          - string
                          - 'null'
                          enum:
                          - stable
                          - caution
                          - risky
                          - null
                          description: The same level /api/offers publishes for the record this name resolved to, from the same function (#1486) — null wherever any rule withholds it, and never substituted with a favourable default.
                        risk_cause:
                          type:
                          - object
                          - 'null'
                          description: The single dated record that produced a non-stable risk_level.
                        gate:
                          type:
                          - object
                          - 'null'
                          description: Non-null for an offer we have decided not to list (#1241). The caller named this vendor, so the gate is reported whether or not a level would have been published.
                        rating_withheld:
                          type:
                          - object
                          - 'null'
                          description: 'Non-null where every record that would have set a non-stable risk_level either carries an empty source_url (no_source, #1352) or is a change our automatic re-read recorded that neither an archived copy of the vendor''s page nor our own check has confirmed (unconfirmed, #1952). The level is withheld rather than reported as stable, and the records are named on the vendor page as unsourced or unconfirmed. Where both kinds are withheld, reason is that of the record that would set the most severe level, and unconfirmed on a tie; records counts both.'
                          properties:
                            reason:
                              type: string
                              enum:
                              - no_source
                              - unconfirmed
                            records:
                              type: number
                        link_unreachable:
                          type:
                          - object
                          - 'null'
                          description: Non-null where the offer's own link is confirmed unreachable (#1046).
                        source_check:
                          type:
                          - object
                          - 'null'
                          description: Our last read of the page we cite. An outcome other than ok withholds a favourable level.
                        level_withheld_because:
                          type:
                          - string
                          - 'null'
                          description: The sentence naming the rule that withheld the level, or null where a level is published. A null risk_level always arrives with one.
                        recent_changes:
                          type: array
                          items:
                            type: object
                        cheaper_alternative:
                          type:
                          - object
                          - 'null'
                          description: A same-category free offer we publish a stable level for. Chosen with the same function as risk_level, so a vendor we decline to rate is never offered as the safer swap (#1486).
                        suggestions:
                          type: array
                          items:
                            type: string
                  recommendations:
                    type: array
                    items:
                      type: string
                  _provenance:
                    $ref: '#/components/schemas/Provenance'
        '400':
          description: Missing services parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
      tags:
      - Audit Stack
      operationId: getApiAuditStack
      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
    TermsSuperseded:
      type:
      - object
      - 'null'
      description: Null unless a dated change record supersedes the terms we stored for this listing. When present, `description` still holds those stored terms, which we no longer publish as current. Use `notice`, or `reading.terms`, the vendor page's text at `reading.url` on `reading.date`.
      properties:
        change_date:
          type: string
          format: date
        change_type:
          type: string
        summary:
          type: string
        reading:
          type:
          - object
          - 'null'
          properties:
            date:
              type: string
              format: date
            url:
              type: string
              format: uri
            label:
              type: string
            terms:
              type: string
          required:
          - date
          - url
          - label
          - terms
        notice:
          type: string
      required:
      - change_date
      - change_type
      - summary
      - reading
      - notice
x-refined-from:
- agentdeals-dev.json
- agentdeals-dev-openapi.json