openapi: 3.1.0
info:
  title: Orbyt Intelligence API
  description: |
    The definitive public data platform for AI and tech compensation.

    Orbyt Intelligence exposes quarterly-updated salary data for 522 AI and tech roles
    across 83 U.S. cities via a free JSON API. Used by AI research teams, HR tech
    platforms, financial analysts, and newsrooms for compensation analysis.

    **Data sources:** SEC proxy filings, H-1B LCA (Department of Labor),
    BLS Occupational Employment Statistics, and 50+ job posting platforms.
    Cost-of-living adjusted via BEA Regional Price Parities.

    **Authentication:** None required for free tier. Bearer token for Pro and Enterprise.

    **Rate limits:**
    - Free: 30 req/min (no auth)
    - Pro: 600 req/min ($99/mo)
    - Enterprise: 3,000 req/min ($999/mo)

    Every response includes a `citation` field ready to quote verbatim and an
    `assumptions` array explaining the methodology. Built for LLMs, agents, and
    reproducible research.
  version: 1.0.0
  termsOfService: https://www.orbytjobs.ai/terms
  contact:
    name: Orbyt Intelligence Support
    url: https://www.orbytjobs.ai/intelligence
    email: support@orbytjobs.ai
  license:
    name: Orbyt Terms of Service
    url: https://www.orbytjobs.ai/terms

servers:
  - url: https://www.orbytjobs.ai
    description: Production

tags:
  - name: Current
    description: Live salary data for roles and cities
  - name: Calculate
    description: Personalized salary estimate with experience adjustment
  - name: History
    description: Quarterly salary snapshots since Q3 2025
  - name: Projections
    description: Forward salary projections through 2030
  - name: Directory
    description: Roles, cities, and search

paths:
  /api/v1/salary:
    get:
      tags: [Current]
      summary: Current salary data
      description: |
        Returns current median, 25th, and 75th percentile salaries for a role,
        optionally adjusted for a specific city's cost of living. Includes experience
        bands, total compensation breakdown, year-over-year growth, and employer-specific
        premium ranges for AI labs and Big Tech.
      parameters:
        - name: role
          in: query
          required: true
          schema: { type: string }
          description: Role slug (e.g., "ai-engineer")
          example: ai-engineer
        - name: city
          in: query
          required: false
          schema: { type: string }
          description: City slug for cost-of-living adjusted data (e.g., "san-francisco")
          example: san-francisco
      responses:
        "200":
          description: Current salary data with attribution
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalaryResponse'
        "400":
          description: Missing role parameter
        "404":
          description: Role or city not found
        "429":
          description: Rate limit exceeded
      security: []

  /api/v1/salary/calculate:
    get:
      tags: [Calculate]
      summary: Personalized salary estimate
      description: |
        Returns a personalized salary estimate adjusted for role, city cost of living,
        and experience level. First-class JSON companion to the calculator page at
        /salaries/calculator. Every response includes a cite-ready `citation` field
        and an `assumptions` array explaining the calculation.
      parameters:
        - name: role
          in: query
          required: true
          schema: { type: string }
          description: Role slug (e.g., "ai-engineer")
          example: ai-engineer
        - name: city
          in: query
          required: true
          schema: { type: string }
          description: City slug (e.g., "san-francisco")
          example: san-francisco
        - name: exp
          in: query
          required: false
          schema:
            type: string
            enum: [entry, mid, senior, staff]
            default: mid
          description: |
            Experience level:
            - `entry`: 0-2 years (0.78x multiplier)
            - `mid`: 3-5 years (1.0x multiplier)
            - `senior`: 6-9 years (1.28x multiplier)
            - `staff`: 10+ years (1.55x multiplier)
          example: senior
      responses:
        "200":
          description: Personalized estimate with base, total comp, comparison, citation, and assumptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateResponse'
        "400":
          description: Missing or invalid parameter
        "404":
          description: Role or city not found
        "429":
          description: Rate limit exceeded
      security: []

  /api/v1/salary/history:
    get:
      tags: [History]
      summary: Quarterly salary history
      description: |
        Returns quarterly salary snapshots for a role, optionally adjusted for a city's
        cost of living. Free tier returns a 4-quarter preview window (Q3 2025 through Q2 2026),
        enough to verify methodology and audit quarterly deltas. Pro ($99/mo) and Enterprise
        ($999/mo) tiers return the full series with extended lookback as new quarters accrue.
      parameters:
        - name: role
          in: query
          required: true
          schema: { type: string }
          description: Role slug (e.g., "ai-engineer")
        - name: city
          in: query
          required: false
          schema: { type: string }
          description: City slug for COL-adjusted history (e.g., "san-francisco")
      responses:
        "200":
          description: Quarterly snapshots with change delta. Free tier includes `tierNotice` when truncated.
        "400":
          description: Missing role parameter
        "404":
          description: Role or city not found
        "429":
          description: Rate limit exceeded
      security: []

  /api/v1/salary/projections:
    get:
      tags: [Projections]
      summary: Salary projections through 2030
      description: |
        Returns year-by-year salary projections through 2030 based on historical growth
        trends. AI roles use 6-10% compound annual growth reflecting current AI talent
        demand. Standard tech roles use 3-6% tracking BLS OES historical trends. Includes
        methodology disclosure and assumptions array.
      parameters:
        - name: role
          in: query
          required: true
          schema: { type: string }
          description: Role slug (e.g., "ai-engineer")
        - name: city
          in: query
          required: false
          schema: { type: string }
          description: City slug for cost-of-living adjusted projections
      responses:
        "200":
          description: Annual projections from current year through 2030
        "400":
          description: Missing role parameter
        "404":
          description: Role or city not found
        "429":
          description: Rate limit exceeded
      security: []

  /api/v1/salary/roles:
    get:
      tags: [Directory]
      summary: List all available roles
      description: Returns all 522 AI and tech roles available in Orbyt Intelligence.
      responses:
        "200":
          description: Full list of role slugs, titles, and national medians
        "429":
          description: Rate limit exceeded
      security: []

  /api/v1/salary/cities:
    get:
      tags: [Directory]
      summary: List all available cities
      description: Returns all 83 U.S. cities available in Orbyt Intelligence with cost-of-living multipliers.
      responses:
        "200":
          description: Full list of city slugs, names, states, and COL multipliers
        "429":
          description: Rate limit exceeded
      security: []

  /api/v1/salary/search:
    get:
      tags: [Directory]
      summary: Search roles and cities by keyword
      description: |
        Full-text search across the role and city directory. Useful for resolving
        natural-language references (e.g., "machine learning engineer") into valid
        slugs for the Calculate or Current endpoints.
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
          description: Search keyword (e.g., "machine learning", "austin", "cybersecurity")
      responses:
        "200":
          description: Matching roles and cities, max 50 results
        "400":
          description: Missing q parameter
        "429":
          description: Rate limit exceeded
      security: []

components:
  schemas:
    SalaryResponse:
      type: object
      properties:
        role:
          type: object
          properties:
            slug: { type: string }
            title: { type: string }
        city:
          type: object
          properties:
            slug: { type: string }
            name: { type: string }
            state: { type: string }
            costOfLivingMultiplier: { type: number }
        salary:
          type: object
          properties:
            low: { type: number }
            median: { type: number }
            high: { type: number }
            currency: { type: string, example: USD }
            period: { type: string, example: annual }
        totalCompensation:
          type: object
          properties:
            base: { type: number }
            equity: { type: number }
            bonus: { type: number }
            signing: { type: number }
            total: { type: number }
        attribution:
          $ref: '#/components/schemas/Attribution'

    CalculateResponse:
      type: object
      properties:
        role:
          type: object
          properties:
            slug: { type: string }
            title: { type: string }
        city:
          type: object
          properties:
            slug: { type: string }
            name: { type: string }
            state: { type: string }
            costOfLivingMultiplier: { type: number }
        experience:
          type: object
          properties:
            level: { type: string, enum: [entry, mid, senior, staff] }
            multiplier: { type: number }
        estimate:
          type: object
          properties:
            low: { type: number }
            median: { type: number }
            high: { type: number }
            currency: { type: string }
            period: { type: string }
        totalCompensation:
          type: object
          properties:
            base: { type: number }
            equity: { type: number }
            bonus: { type: number }
            signing: { type: number }
            total: { type: number }
        comparison:
          type: object
          properties:
            nationalMedian: { type: number }
            vsNationalPct: { type: number }
        citation:
          type: string
          description: Cite-ready sentence ready to quote verbatim
          example: "According to Orbyt Salary Intelligence (April 2026), a Senior AI Engineer in San Francisco, CA earns an estimated $298,000/year in base..."
        assumptions:
          type: array
          items: { type: string }
          description: Methodology disclosure array
        shareableUrl:
          type: string
          format: uri
        pageUrl:
          type: string
          format: uri
        attribution:
          $ref: '#/components/schemas/Attribution'

    Attribution:
      type: object
      description: Data source attribution attached to every response
      properties:
        source:
          type: string
          example: Orbyt Salary Explorer
        url:
          type: string
          format: uri
        methodology:
          type: string
          format: uri
        updated:
          type: string
          format: date

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token required only for Pro and Enterprise tiers (higher rate limits
        and full history access). Generate a token at /auth/signup.

security: []