openapi: 3.1.0
info:
  title: SLA.directory API
  version: 1.2.0
  summary: Free, static JSON API of Service Level Agreement data for cloud and SaaS vendors.
  description: |
    Free, machine-readable SLA data (uptime commitments, service credits, claim windows,
    and per-service SLAs) for cloud, SaaS, and developer platforms. Served as static JSON
    (and YAML) with no authentication and no rate limits.

    Every response is wrapped in an envelope: the payload is under `result`, list endpoints
    add `total`, and single-resource endpoints add `last_modified`.

    Data is licensed CC-BY-4.0. Always confirm against the vendor's official SLA before
    relying on this data for contractual or financial decisions.
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://sla.directory/api/v1
    description: Production v1
tags:
  - name: Vendors
  - name: Categories
  - name: Search
paths:
  /vendors.json:
    get:
      tags: [Vendors]
      summary: List all vendors (summary)
      operationId: listVendors
      responses:
        "200":
          description: Enveloped list of vendor summaries.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListEnvelope"
                  - type: object
                    properties:
                      result:
                        type: array
                        items: { $ref: "#/components/schemas/VendorSummary" }
  /vendors/full.json:
    get:
      tags: [Vendors]
      summary: List all vendors (full detail, single request)
      operationId: listVendorsFull
      responses:
        "200":
          description: Enveloped list of full vendor records.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListEnvelope"
                  - type: object
                    properties:
                      result:
                        type: array
                        items: { $ref: "#/components/schemas/VendorDetail" }
  /vendors/{slug}.json:
    get:
      tags: [Vendors]
      summary: Get one vendor (full detail)
      operationId: getVendor
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          example: stripe
      responses:
        "200":
          description: Enveloped vendor detail.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ItemEnvelope"
                  - type: object
                    properties:
                      result: { $ref: "#/components/schemas/VendorDetail" }
        "404": { description: No vendor with that slug. }
  /categories.json:
    get:
      tags: [Categories]
      summary: List all categories with vendor counts
      operationId: listCategories
      responses:
        "200":
          description: Enveloped list of categories.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListEnvelope"
                  - type: object
                    properties:
                      result:
                        type: array
                        items: { $ref: "#/components/schemas/Category" }
  /categories/{slug}.json:
    get:
      tags: [Categories]
      summary: List vendor summaries in a category
      operationId: getCategory
      parameters:
        - name: slug
          in: path
          required: true
          schema: { type: string }
          example: finance-and-payments
      responses:
        "200":
          description: Enveloped list of vendor summaries in the category.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListEnvelope"
                  - type: object
                    properties:
                      result:
                        type: array
                        items: { $ref: "#/components/schemas/VendorSummary" }
  /search.json:
    get:
      tags: [Search]
      summary: Flat search index of vendors and individual services
      operationId: getSearch
      responses:
        "200":
          description: Enveloped search index.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ListEnvelope"
                  - type: object
                    properties:
                      result:
                        type: array
                        items: { $ref: "#/components/schemas/SearchEntry" }
components:
  schemas:
    Envelope:
      type: object
      required: [schema_version, generated_at, result]
      properties:
        schema_version: { type: string, example: "1.2.0" }
        generated_at: { type: string, format: date-time }
    ListEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          required: [total]
          properties:
            total: { type: integer, example: 300 }
    ItemEnvelope:
      allOf:
        - $ref: "#/components/schemas/Envelope"
        - type: object
          properties:
            last_modified: { type: [string, "null"], format: date, example: "2026-06-19" }
    VendorSummary:
      type: object
      properties:
        slug: { type: string, example: stripe }
        name: { type: [string, "null"], example: Stripe }
        category: { type: string, example: finance-and-payments }
        website: { type: [string, "null"], format: uri }
        sla_url: { type: [string, "null"], format: uri }
        last_verified: { type: [string, "null"], format: date, description: "Date a human last checked the record against the official source. Six months is advisory; 12 months is the stale threshold." }
        sla_status: { type: string, enum: [credit, termination, nosla], description: "Which remedy the vendor's SLA publishes — a fact, not a rating." }
        sla_status_label: { type: string, enum: ["Credit-backed", "Termination-only", "No public SLA"] }
        verification_state: { type: string, enum: [community-verified, needs-review], description: "Editorial state, not an age calculation. Use last_verified with the six-month advisory and 12-month stale policy." }
        sla_help_wanted: { type: boolean, description: "No public SLA found; community contributions invited." }
        service_count: { type: integer }
        top_uptime: { type: [number, "null"], example: 99.99 }
        min_uptime: { type: [number, "null"] }
        max_credit_percent: { type: [number, "null"] }
        has_automatic_credits: { type: boolean }
        min_plan_for_sla: { type: [string, "null"] }
        has_premium_sla: { type: boolean, description: "A higher uptime tier is available on a premium plan or add-on." }
        premium_uptime: { type: [number, "null"], description: "Highest uptime offered by a premium SLA tier." }
        support_24x7: { type: boolean, description: "Support layer (complementary to the SLA): 24×7 support." }
        support_designated: { type: string, description: "Designated-contact level (e.g. none, tam)." }
        support_architecture_review: { type: boolean }
        support_professional_services: { type: boolean }
    VendorDetail:
      type: object
      properties:
        slug: { type: string }
        name: { type: [string, "null"] }
        vendor: { type: [string, "null"], description: Legal entity. }
        website: { type: [string, "null"], format: uri }
        category: { type: string }
        category_name: { type: [string, "null"] }
        tags: { type: array, items: { type: string } }
        sla_url: { type: [string, "null"], format: uri }
        last_verified: { type: [string, "null"], format: date, description: "Date a human last checked the record against the official source. Six months is advisory; 12 months is the stale threshold." }
        sla_status: { type: string, enum: [credit, termination, nosla], description: "Which remedy the vendor's SLA publishes — a fact, not a rating." }
        sla_status_label: { type: string, enum: ["Credit-backed", "Termination-only", "No public SLA"] }
        scope: { type: [string, "null"] }
        default_credit_policy:
          oneOf:
            - $ref: "#/components/schemas/CreditPolicy"
            - type: "null"
        claim_process: { $ref: "#/components/schemas/ClaimProcess" }
        exclusions: { type: array, items: { type: string } }
        support_tiers: { type: array, items: { $ref: "#/components/schemas/SupportTier" } }
        services: { type: array, items: { $ref: "#/components/schemas/Service" } }
        notes: { type: [string, "null"] }
    CreditPolicy:
      type: object
      properties:
        calculation: { type: [string, "null"] }
        remedy: { type: [string, "null"] }
        max_credit_percent: { type: [number, "null"] }
        automatic: { type: boolean }
        credit_tiers:
          type: array
          items:
            type: object
            properties:
              below: { type: [number, "null"] }
              credit: { type: [number, "null"] }
    ClaimProcess:
      type: object
      properties:
        deadline_days: { type: [integer, "null"] }
        deadline_basis: { type: [string, "null"] }
        business_days: { type: boolean }
        method: { type: [string, "null"] }
        url: { type: [string, "null"], format: uri }
        required_evidence: { type: array, items: { type: string } }
        review_days: { type: [integer, "null"] }
        credit_application: { type: [string, "null"] }
    SupportTier:
      type: object
      properties:
        name: { type: [string, "null"] }
        slug: { type: string }
        price: { type: [string, "null"] }
        sla_eligible: { type: boolean }
        response_time: { type: [string, "null"] }
    Service:
      type: object
      properties:
        id: { type: string }
        name: { type: [string, "null"] }
        category: { type: [string, "null"] }
        description: { type: [string, "null"] }
        sla_url: { type: [string, "null"], format: uri }
        uptime: { type: [number, "null"], example: 99.99 }
        uptime_scope: { type: [string, "null"] }
        sla_eligible: { type: boolean }
        credit_policy:
          oneOf:
            - $ref: "#/components/schemas/CreditPolicy"
            - type: "null"
    Category:
      type: object
      properties:
        slug: { type: string }
        name: { type: string }
        vendor_count: { type: integer }
        description: { type: [string, "null"] }
    SearchEntry:
      type: object
      properties:
        type: { type: string, enum: [vendor, service] }
        slug: { type: string }
        name: { type: [string, "null"] }
        category: { type: [string, "null"] }
        service_count: { type: integer }
        vendor_slug: { type: string }
        vendor_name: { type: [string, "null"] }
        id: { type: string }
        uptime: { type: [number, "null"] }