{
  "openapi": "3.1.0",
  "info": {
    "title": "Aeonix Tech AI Opportunity Index API",
    "version": "1.0.0",
    "description": "Read-only access to Aeonix Tech's public AI Opportunity Index for 342 United States occupations. Search the collection or retrieve one exact occupation by slug. The API uses stable URL path versioning. Breaking changes receive a new major path such as /api/v2; compatible additions remain within /api/v1. Deprecations are announced through the Deprecation response header and rel=deprecation link, and a scheduled retirement receives a Sunset header at least 180 days before removal. The index is informational research, not employment, financial, legal, or professional advice.",
    "termsOfService": "https://www.aeonixtech.com/terms",
    "license": {
      "name": "Aeonix Tech Website Terms of Use",
      "url": "https://www.aeonixtech.com/terms"
    },
    "contact": {
      "name": "Aeonix Tech",
      "url": "https://www.aeonixtech.com/contact",
      "email": "contact@aeonixtech.com"
    }
  },
  "servers": [
    {
      "url": "https://www.aeonixtech.com",
      "description": "Aeonix Tech production API"
    }
  ],
  "tags": [
    {
      "name": "AI Opportunity Index",
      "description": "Public, read-only occupational AI exposure and opportunity research."
    }
  ],
  "externalDocs": {
    "description": "Aeonix Tech developer documentation, versioning, deprecation, and rate-limit policy",
    "url": "https://www.aeonixtech.com/developers"
  },
  "paths": {
    "/api/v1/ai-opportunity-index": {
      "get": {
        "operationId": "searchAiOpportunityIndexOccupations",
        "summary": "Search occupations or retrieve one occupation",
        "description": "Returns a paginated collection of occupations, optionally filtered with q, or one exact occupation when slug is supplied. q and slug are mutually exclusive. This stable v1 endpoint is read-only, requires no authentication, and never changes site or client data. Clients may send up to 120 requests per 60-second window and should pace requests using the RateLimit response fields.",
        "tags": ["AI Opportunity Index"],
        "security": [],
        "parameters": [
          {
            "in": "query",
            "name": "q",
            "required": false,
            "description": "Case-insensitive substring search across occupation title, slug, and category. Cannot be combined with slug.",
            "schema": {
              "type": "string",
              "maxLength": 100
            },
            "example": "software"
          },
          {
            "in": "query",
            "name": "slug",
            "required": false,
            "description": "Exact occupation slug. Returns one occupation and cannot be combined with q.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
            },
            "example": "software-developers"
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "description": "Maximum collection results to return. Ignored for an exact slug lookup.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          },
          {
            "in": "query",
            "name": "offset",
            "required": false,
            "description": "Zero-based collection offset. Ignored for an exact slug lookup.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 342,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A collection page or one exact occupation",
            "headers": {
              "Cache-Control": {
                "description": "Private no-store policy so each request receives current client-specific rate-limit state.",
                "schema": { "type": "string" }
              },
              "Link": {
                "description": "Links to the OpenAPI description and human-readable documentation.",
                "schema": { "type": "string" }
              },
              "Vary": {
                "description": "Response cache variation fields.",
                "schema": { "type": "string" }
              },
              "RateLimit-Policy": {
                "description": "Current IETF structured rate-limit policy field. The policy allows 120 requests in a 60-second window.",
                "schema": { "type": "string" },
                "example": "\"ai-opportunity-index\";q=120;w=60"
              },
              "RateLimit": {
                "description": "Current IETF structured rate-limit status field with remaining quota and reset delay in seconds.",
                "schema": { "type": "string" },
                "example": "\"ai-opportunity-index\";r=119;t=60"
              },
              "RateLimit-Limit": {
                "description": "Compatibility field for the request limit.",
                "schema": { "type": "integer" },
                "example": 120
              },
              "RateLimit-Remaining": {
                "description": "Compatibility field for requests remaining in the current window.",
                "schema": { "type": "integer" },
                "example": 119
              },
              "RateLimit-Reset": {
                "description": "Compatibility field for seconds until the current window resets.",
                "schema": { "type": "integer" },
                "example": 60
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    { "$ref": "#/components/schemas/OccupationCollectionResponse" },
                    { "$ref": "#/components/schemas/OccupationResponse" }
                  ]
                },
                "examples": {
                  "exactOccupation": {
                    "summary": "Exact occupation lookup",
                    "value": {
                      "api_version": "1.0",
                      "data": {
                        "title": "Software developers",
                        "slug": "software-developers",
                        "category": "computer-and-information-technology",
                        "pay": 132270,
                        "jobs": 1895500,
                        "outlook": 26,
                        "outlook_desc": "Much faster than average",
                        "education": "Bachelor's degree",
                        "exposure": 9,
                        "exposure_rationale": "Software development is highly exposed to AI-assisted implementation.",
                        "advantage": 9,
                        "advantage_rationale": "Developers can use AI across implementation, testing, and analysis.",
                        "growth": 9,
                        "growth_rationale": "Demand for software remains strong as the cost of building falls.",
                        "opportunity": 9,
                        "url": "https://www.bls.gov/ooh/computer-and-information-technology/software-developers.htm",
                        "human_edge": "System design, product judgment, accountability, and contextual decisions remain human responsibilities."
                      },
                      "meta": {
                        "name": "Aeonix Tech AI Opportunity Index",
                        "description": "Directional analysis of AI exposure, AI advantage, job growth, and AI opportunity across 342 United States occupations.",
                        "methodology_url": "https://www.aeonixtech.com/ai-opportunity-index",
                        "disclaimer": "Informational research only."
                      },
                      "links": {
                        "self": "https://www.aeonixtech.com/api/v1/ai-opportunity-index?slug=software-developers",
                        "human": "https://www.aeonixtech.com/ai-opportunity-index",
                        "documentation": "https://www.aeonixtech.com/developers",
                        "openapi": "https://www.aeonixtech.com/openapi.json"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "One or more query parameters are invalid",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ProblemDetails" }
              }
            }
          },
          "404": {
            "description": "No occupation matches the exact slug",
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ProblemDetails" }
              }
            }
          },
          "405": {
            "description": "The endpoint received a method other than GET, HEAD, or OPTIONS",
            "headers": {
              "Allow": {
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ProblemDetails" }
              }
            }
          },
          "429": {
            "description": "The client exceeded 120 requests in the current 60-second window",
            "headers": {
              "Retry-After": {
                "description": "Seconds the client should wait before retrying.",
                "schema": { "type": "integer", "minimum": 1 }
              },
              "RateLimit-Policy": {
                "description": "Current IETF structured rate-limit policy field.",
                "schema": { "type": "string" }
              },
              "RateLimit": {
                "description": "Current IETF structured rate-limit status field with zero remaining quota.",
                "schema": { "type": "string" }
              }
            },
            "content": {
              "application/problem+json": {
                "schema": { "$ref": "#/components/schemas/ProblemDetails" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Occupation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "title",
          "slug",
          "category",
          "pay",
          "jobs",
          "outlook",
          "outlook_desc",
          "education",
          "exposure",
          "exposure_rationale",
          "advantage",
          "advantage_rationale",
          "growth",
          "growth_rationale",
          "opportunity",
          "url",
          "human_edge"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Human-readable occupation title."
          },
          "slug": {
            "type": "string",
            "description": "Stable lowercase identifier for exact lookup."
          },
          "category": {
            "type": "string",
            "description": "Occupational category identifier."
          },
          "pay": {
            "type": "integer",
            "minimum": 0,
            "description": "Median annual pay in United States dollars from the source dataset."
          },
          "jobs": {
            "type": "integer",
            "minimum": 0,
            "description": "Estimated number of United States jobs represented by the occupation."
          },
          "outlook": {
            "type": "number",
            "description": "Published employment outlook percentage associated with the occupation."
          },
          "outlook_desc": {
            "type": "string",
            "description": "Human-readable employment outlook category."
          },
          "education": {
            "type": "string",
            "description": "Typical entry-level education associated with the occupation."
          },
          "exposure": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Directional score for how much core work AI can perform or reshape."
          },
          "exposure_rationale": {
            "type": "string",
            "description": "Explanation supporting the AI exposure score."
          },
          "advantage": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Directional score for how much practitioners can benefit from AI adoption."
          },
          "advantage_rationale": {
            "type": "string",
            "description": "Explanation supporting the AI advantage score."
          },
          "growth": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Normalized job-growth score used by the index."
          },
          "growth_rationale": {
            "type": "string",
            "description": "Explanation supporting the job-growth score."
          },
          "opportunity": {
            "type": "number",
            "minimum": 0,
            "maximum": 10,
            "description": "Composite AI opportunity score used by the index."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Authoritative occupational source URL."
          },
          "human_edge": {
            "type": "string",
            "description": "Occupation-specific analysis of consequential human work that AI does not replace."
          }
        }
      },
      "CollectionMeta": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "description", "methodology_url", "disclaimer"],
        "properties": {
          "name": { "type": "string" },
          "description": { "type": "string" },
          "methodology_url": { "type": "string", "format": "uri" },
          "disclaimer": { "type": "string" },
          "total": { "type": "integer", "minimum": 0 },
          "returned": { "type": "integer", "minimum": 0 },
          "limit": { "type": "integer", "minimum": 1, "maximum": 50 },
          "offset": { "type": "integer", "minimum": 0 },
          "query": { "type": ["string", "null"] }
        }
      },
      "ResponseLinks": {
        "type": "object",
        "additionalProperties": false,
        "required": ["self", "documentation", "openapi"],
        "properties": {
          "self": { "type": "string", "format": "uri" },
          "next": { "type": ["string", "null"], "format": "uri" },
          "human": { "type": "string", "format": "uri" },
          "documentation": { "type": "string", "format": "uri" },
          "openapi": { "type": "string", "format": "uri" }
        }
      },
      "OccupationCollectionResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "data", "meta", "links"],
        "properties": {
          "api_version": { "type": "string", "const": "1.0" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Occupation" }
          },
          "meta": { "$ref": "#/components/schemas/CollectionMeta" },
          "links": { "$ref": "#/components/schemas/ResponseLinks" }
        }
      },
      "OccupationResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["api_version", "data", "meta", "links"],
        "properties": {
          "api_version": { "type": "string", "const": "1.0" },
          "data": { "$ref": "#/components/schemas/Occupation" },
          "meta": { "$ref": "#/components/schemas/CollectionMeta" },
          "links": { "$ref": "#/components/schemas/ResponseLinks" }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "resolution",
          "documentation_url"
        ],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer", "minimum": 400, "maximum": 599 },
          "detail": { "type": "string" },
          "instance": { "type": "string", "format": "uri" },
          "code": { "type": "string" },
          "resolution": { "type": "string" },
          "documentation_url": { "type": "string", "format": "uri" }
        }
      }
    }
  }
}