openapi: 3.0.3
info:
  title: ConnectVFX Developer REST API
  description: Structured, software-enriched Visual Effects, 3D animation, and gaming graphics job feed API with transparent 302 ATS application redirects.
  version: 1.1.0
  contact:
    name: ConnectVFX Developer Support
    url: https://connectvfx.app/external-docs
servers:
  - url: https://connectvfx.app/api
    description: Production API Gateway

security:
  - BearerAuth: []

paths:
  /external-jobs:
    get:
      summary: Retrieve Paginated Active Jobs
      description: Returns active, software-enriched job listings with domain taxonomy, studio metadata, geographic normalization, salary bounds, canonical job URLs, and 302 application redirect links.
      parameters:
        - name: software
          in: query
          required: false
          description: Filter roles requiring specific software (e.g. Houdini, Nuke, Unreal, Maya, Blender).
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Free-text search matching titles, studios, or locations.
          schema:
            type: string
        - name: department
          in: query
          required: false
          description: Filter by discipline (e.g. FX / Simulation, Compositing, Animation, Lighting / LookDev).
          schema:
            type: string
        - name: remote
          in: query
          required: false
          description: Filter exclusively for remote-eligible roles.
          schema:
            type: boolean
        - name: limit
          in: query
          required: false
          description: Number of records per page (min 1, max 100).
          schema:
            type: integer
            default: 50
        - name: page
          in: query
          required: false
          description: Page index (0-indexed).
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Successful response returning structured jobs array and pagination metadata.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per minute (default 30).
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining requests in the current rate limit window.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobListing'
                  total:
                    type: integer
                  page:
                    type: integer
                  limit:
                    type: integer
                  pages_total:
                    type: integer
        '400':
          description: Invalid query parameters.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limit or monthly record quota exceeded.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
        '500':
          description: Internal server error.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: APIKey
  schemas:
    JobListing:
      type: object
      properties:
        id:
          type: string
          example: "job_e83f912a781b"
        uuid:
          type: string
          example: "45ff7619-d5c5-49fa-bd36-77c6e97aed8a"
        title:
          type: string
          example: "Senior FX Animator (Houdini)"
        discipline:
          type: string
          example: "FX / Simulation"
        seniority:
          type: string
          example: "Senior"
        company:
          type: string
          example: "Industrial Light & Magic"
        company_slug:
          type: string
          example: "industrial-light-magic"
        displayLocation:
          type: string
          example: "Vancouver, Canada"
        city:
          type: string
          example: "Vancouver"
        country:
          type: string
          example: "Canada"
        country_iso:
          type: string
          example: "CA"
        is_remote:
          type: boolean
        contract_type:
          type: string
          example: "full-time"
        softwares:
          type: object
          properties:
            must:
              type: array
              items:
                type: string
              example: ["Houdini"]
            bonus:
              type: array
              items:
                type: string
              example: ["Nuke", "Python"]
        description_snippet:
          type: string
        studio_location_hq:
          type: string
          example: "San Francisco, CA, USA"
        studio_employee_count:
          type: string
          example: "1000-5000"
        studio_size_category:
          type: string
          example: "Major Studio"
        studio_locations:
          type: string
          example: "San Francisco, Vancouver, London, Singapore, Sydney"
        salary_raw:
          type: string
          nullable: true
          example: "$115,000 - $140,000 / year"
        salary_currency_local:
          type: string
          nullable: true
          example: "USD"
        salary_min_usd:
          type: integer
          nullable: true
          example: 115000
        salary_max_usd:
          type: integer
          nullable: true
          example: 140000
        job_url:
          type: string
          description: Canonical indexable ConnectVFX web page for attribution and details.
          example: "https://connectvfx.app/jobs/industrial-light-magic/senior-fx-animator-houdini"
        apply_url:
          type: string
          description: Direct candidate application route pointing to the studio's active application portal when available.
          example: "https://connectvfx.app/api/apply?id=job_e83f912a781b&ref=pub_your_id"
        firstSeen:
          type: string
          format: date-time
        lastSeen:
          type: string
          format: date-time
        is_active:
          type: boolean
          example: true