{
  "openapi": "3.1.0",
  "info": {
    "title": "Recruiter Roles API",
    "description": "Free API for recruiter and talent acquisition job listings, company profiles, sectors, locations, and market stats.",
    "version": "1.0.0",
    "contact": {
      "email": "hello@recruiterroles.com",
      "url": "https://recruiterroles.com/api-docs"
    },
    "license": {
      "name": "Backlink required",
      "url": "https://recruiterroles.com/api-docs#backlink"
    }
  },
  "servers": [
    {
      "url": "https://recruiterroles.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [{ "BearerAuth": [] }],
  "paths": {
    "/jobs": {
      "get": {
        "operationId": "listJobs",
        "summary": "List jobs",
        "description": "Paginated list of active recruiter job listings with filtering and search.",
        "tags": ["Jobs"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Full-text search (title, company name)"
          },
          {
            "name": "sector",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Sector slug. Comma-separated for multiple."
          },
          {
            "name": "state",
            "in": "query",
            "schema": { "type": "string" },
            "description": "State/region code (e.g., TX, NY, BC). Comma-separated."
          },
          {
            "name": "city",
            "in": "query",
            "schema": { "type": "string" },
            "description": "City slug. Comma-separated."
          },
          {
            "name": "employment_type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["full_time", "part_time", "contract", "freelance"]
            },
            "description": "Employment type filter"
          },
          {
            "name": "work_arrangement",
            "in": "query",
            "schema": { "type": "string", "enum": ["on_site", "hybrid", "remote"] },
            "description": "Work arrangement filter"
          },
          {
            "name": "is_remote",
            "in": "query",
            "schema": { "type": "boolean" },
            "description": "Shorthand for work_arrangement=remote"
          },
          {
            "name": "salary_min",
            "in": "query",
            "schema": { "type": "integer" },
            "description": "Minimum salary in USD. Only returns disclosed salaries at or above this amount."
          },
          {
            "name": "salary_disclosed",
            "in": "query",
            "schema": { "type": "boolean" },
            "description": "true = only disclosed; false = only undisclosed"
          },
          {
            "name": "source_type",
            "in": "query",
            "schema": { "type": "string", "enum": ["direct", "scraped"] },
            "description": "direct (employer-posted) or scraped"
          },
          {
            "name": "posted_since",
            "in": "query",
            "schema": { "type": "string", "format": "date" },
            "description": "ISO date. Jobs posted on or after this date."
          },
          {
            "name": "updated_since",
            "in": "query",
            "schema": { "type": "string", "format": "date-time" },
            "description": "ISO datetime. For incremental sync."
          },
          {
            "name": "sort",
            "in": "query",
            "schema": { "type": "string", "enum": ["recent", "salary_desc"], "default": "recent" },
            "description": "Sort order"
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 },
            "description": "Page number"
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": { "type": "integer", "default": 20, "maximum": 100 },
            "description": "Results per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of jobs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/JobListItem" }
                    },
                    "meta": { "$ref": "#/components/schemas/Pagination" },
                    "response_generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/jobs/{slug}": {
      "get": {
        "operationId": "getJob",
        "summary": "Get job detail",
        "description": "Full detail for a single job listing including description, requirements, benefits, and tech stack.",
        "tags": ["Jobs"],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Job slug"
          }
        ],
        "responses": {
          "200": {
            "description": "Job detail",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/JobDetail" }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/companies": {
      "get": {
        "operationId": "listCompanies",
        "summary": "List companies",
        "description": "Paginated directory of recruiting companies with active job counts.",
        "tags": ["Companies"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Search company name"
          },
          {
            "name": "company_type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "staffing_agency",
                "executive_search",
                "boutique_firm",
                "corporate_inhouse",
                "rpo",
                "other"
              ]
            },
            "description": "Company type filter"
          },
          {
            "name": "country",
            "in": "query",
            "schema": { "type": "string" },
            "description": "HQ country code (e.g., US, GB)"
          },
          {
            "name": "sort",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["job_count", "name", "recent"],
              "default": "job_count"
            },
            "description": "Sort order"
          },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          {
            "name": "per_page",
            "in": "query",
            "schema": { "type": "integer", "default": 20, "maximum": 100 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated company list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/CompanyListItem" }
                    },
                    "meta": { "$ref": "#/components/schemas/Pagination" },
                    "response_generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/companies/{slug}": {
      "get": {
        "operationId": "getCompany",
        "summary": "Get company profile",
        "description": "Full company profile with paginated list of their active jobs.",
        "tags": ["Companies"],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 },
            "description": "Page of jobs"
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": { "type": "integer", "default": 20, "maximum": 100 },
            "description": "Jobs per page"
          }
        ],
        "responses": {
          "200": {
            "description": "Company profile with jobs",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/CompanyDetail" },
                    "response_generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/sectors": {
      "get": {
        "operationId": "listSectors",
        "summary": "List sectors",
        "description": "All 9 recruiting sectors with current active job counts.",
        "tags": ["Reference Data"],
        "responses": {
          "200": {
            "description": "Sector list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": { "type": "string", "example": "technology" },
                          "name": { "type": "string", "example": "Technology" },
                          "job_count": { "type": "integer", "example": 148 }
                        }
                      }
                    },
                    "response_generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/locations": {
      "get": {
        "operationId": "listLocations",
        "summary": "List locations",
        "description": "Location hierarchy: countries, regions (states/provinces), or cities with active job counts.",
        "tags": ["Reference Data"],
        "parameters": [
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["countries", "regions", "cities"],
              "default": "countries"
            },
            "description": "Which level to return"
          },
          {
            "name": "country",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter by country code (e.g., US, GB)"
          },
          {
            "name": "region",
            "in": "query",
            "schema": { "type": "string" },
            "description": "Filter cities by region code (e.g., TX, CA)"
          }
        ],
        "responses": {
          "200": {
            "description": "Location list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "type": "array", "items": { "type": "object" } },
                    "response_generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid level parameter" }
        }
      }
    },
    "/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Market stats",
        "description": "Aggregate market overview: total jobs, posting velocity, breakdowns by sector, employment type, work arrangement, and top countries.",
        "tags": ["Reference Data"],
        "responses": {
          "200": {
            "description": "Market stats",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": { "$ref": "#/components/schemas/MarketStats" },
                    "response_generated_at": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key issued from https://recruiterroles.com/api-access. Format: rr_live_[32 hex chars]"
      }
    },
    "schemas": {
      "JobListItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string", "example": "senior-recruiter-kforce-a1b2c3" },
          "title": { "type": "string", "example": "Senior Technical Recruiter" },
          "company_name": { "type": "string", "example": "Kforce" },
          "company_website": { "type": "string", "nullable": true },
          "company_logo_url": { "type": "string", "nullable": true },
          "location": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "nullable": true },
              "state": { "type": "string", "nullable": true },
              "is_remote": { "type": "boolean" },
              "work_arrangement": {
                "type": "string",
                "nullable": true,
                "enum": ["on_site", "hybrid", "remote", null]
              }
            }
          },
          "employment_type": {
            "type": "string",
            "enum": ["full_time", "part_time", "contract", "freelance"]
          },
          "primary_sector": { "type": "string", "nullable": true },
          "secondary_sectors": { "type": "array", "items": { "type": "string" } },
          "salary": {
            "type": "object",
            "properties": {
              "disclosed": { "type": "boolean" },
              "min_dollars": { "type": "integer", "nullable": true },
              "max_dollars": { "type": "integer", "nullable": true },
              "currency": { "type": "string", "example": "USD" }
            }
          },
          "commission": {
            "type": "object",
            "properties": {
              "disclosed": { "type": "boolean" },
              "details": { "type": "string", "nullable": true }
            }
          },
          "billing_target": {
            "type": "object",
            "properties": {
              "disclosed": { "type": "boolean" },
              "details": { "type": "string", "nullable": true }
            }
          },
          "description_excerpt": { "type": "string" },
          "source_type": { "type": "string", "enum": ["direct", "scraped"] },
          "apply_url": { "type": "string", "nullable": true },
          "url": { "type": "string", "description": "Tracked redirect URL — use for linking" },
          "canonical_url": { "type": "string", "description": "Direct page URL — use for display" },
          "posted_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" },
          "expires_at": { "type": "string", "format": "date-time", "nullable": true },
          "is_featured": { "type": "boolean" },
          "is_homepage_featured": { "type": "boolean" }
        }
      },
      "JobDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/JobListItem" },
          {
            "type": "object",
            "properties": {
              "description": { "type": "string", "description": "Full plain-text description" },
              "requirements": { "type": "string", "nullable": true },
              "benefits": { "type": "string", "nullable": true },
              "tech_stack": { "type": "array", "items": { "type": "string" } },
              "team_size": { "type": "string", "nullable": true },
              "apply_email": { "type": "string", "nullable": true },
              "is_sticky": { "type": "boolean" }
            }
          }
        ]
      },
      "CompanyListItem": {
        "type": "object",
        "properties": {
          "slug": { "type": "string" },
          "name": { "type": "string" },
          "logo_url": { "type": "string", "nullable": true },
          "description": { "type": "string", "nullable": true, "description": "200-char excerpt" },
          "website_url": { "type": "string", "nullable": true },
          "linkedin_url": { "type": "string", "nullable": true },
          "company_type": {
            "type": "string",
            "nullable": true,
            "enum": [
              "staffing_agency",
              "executive_search",
              "boutique_firm",
              "corporate_inhouse",
              "rpo",
              "other",
              null
            ]
          },
          "employee_count_range": { "type": "string", "nullable": true },
          "headquarters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "nullable": true },
              "state": { "type": "string", "nullable": true },
              "country": { "type": "string", "nullable": true }
            }
          },
          "specialties": { "type": "array", "items": { "type": "string" } },
          "founded_year": { "type": "integer", "nullable": true },
          "is_verified": { "type": "boolean" },
          "active_job_count": { "type": "integer" }
        }
      },
      "CompanyDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/CompanyListItem" },
          {
            "type": "object",
            "properties": {
              "twitter_url": { "type": "string", "nullable": true },
              "careers_page_url": { "type": "string", "nullable": true },
              "url": { "type": "string", "description": "Company page on Recruiter Roles" },
              "jobs": {
                "type": "object",
                "properties": {
                  "data": { "type": "array", "items": { "type": "object" } },
                  "meta": { "$ref": "#/components/schemas/Pagination" }
                }
              }
            }
          }
        ]
      },
      "MarketStats": {
        "type": "object",
        "properties": {
          "total_active_jobs": { "type": "integer", "example": 711 },
          "jobs_posted_24h": { "type": "integer", "example": 24 },
          "jobs_posted_7d": { "type": "integer", "example": 173 },
          "by_sector": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "slug": { "type": "string" },
                "name": { "type": "string" },
                "count": { "type": "integer" }
              }
            }
          },
          "by_employment_type": { "type": "object", "additionalProperties": { "type": "integer" } },
          "by_work_arrangement": {
            "type": "object",
            "properties": {
              "on_site": { "type": "integer" },
              "hybrid": { "type": "integer" },
              "remote": { "type": "integer" }
            }
          },
          "top_countries": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "count": { "type": "integer" }
              }
            }
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "per_page": { "type": "integer" },
          "total_pages": { "type": "integer" },
          "next_page": { "type": "integer", "nullable": true },
          "prev_page": { "type": "integer", "nullable": true }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "message": { "type": "string" }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Daily rate limit exceeded",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}