{
  "openapi": "3.1.0",
  "info": {
    "title": "Mike is Hiring Public API",
    "version": "1.0.0",
    "summary": "Source-tracked AI and crypto hiring intelligence for people and agents.",
    "description": "Zero-auth public read endpoints for API discovery, current job search, job details, market-map readiness, company interview research, and MCP health. Check each response's source and freshness metadata before presenting a result as current.",
    "contact": {
      "name": "Mike is Hiring developer support",
      "url": "https://mikeishiring.com/contact",
      "email": "hello@mikeishiring.com"
    }
  },
  "servers": [
    {
      "url": "https://mikeishiring.com",
      "description": "Canonical production origin"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Developer portal and integration quickstarts",
    "url": "https://mikeishiring.com/developers"
  },
  "tags": [
    { "name": "Discovery", "description": "Machine-readable API and service discovery." },
    { "name": "Jobs", "description": "Current public job read models." },
    { "name": "Market", "description": "Aggregate market-readiness metadata." },
    { "name": "Companies", "description": "Source-backed company interview research." },
    { "name": "Operations", "description": "Read-only service health." }
  ],
  "paths": {
    "/api/public/v1": {
      "get": {
        "operationId": "discoverPublicApi",
        "summary": "Discover the public API",
        "description": "Returns the deployed public endpoint catalog, authentication boundary, envelope conventions, and snapshot freshness metadata. Call this before assuming an endpoint exists.",
        "tags": ["Discovery"],
        "responses": {
          "200": {
            "description": "The deployed public API catalog.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/DiscoveryResponse" }
              }
            }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/public/v1/search/jobs": {
      "get": {
        "operationId": "searchPublicJobs",
        "summary": "Search current jobs",
        "description": "Searches the current public job read model. Use a bounded query and fetch each selected job's detail record before recommending or preparing an application.",
        "tags": ["Jobs"],
        "parameters": [
          { "$ref": "#/components/parameters/Query" },
          { "$ref": "#/components/parameters/Domain" },
          { "$ref": "#/components/parameters/Skills" },
          { "$ref": "#/components/parameters/SkillMatch" },
          { "$ref": "#/components/parameters/CompanyType" },
          { "$ref": "#/components/parameters/Seniority" },
          { "$ref": "#/components/parameters/RemoteOnly" },
          { "$ref": "#/components/parameters/LocationCountry" },
          { "$ref": "#/components/parameters/MinimumSalary" },
          { "$ref": "#/components/parameters/MaximumSalary" },
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/IncludePredictedSalaries" }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of current jobs and read-model metadata.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public/v1/jobs": {
      "get": {
        "operationId": "listPublicJobs",
        "summary": "List current jobs",
        "description": "Lists current jobs from the public read model using the same typed filters as search. Prefer the search operation when supplying free text.",
        "tags": ["Jobs"],
        "parameters": [
          { "$ref": "#/components/parameters/Query" },
          { "$ref": "#/components/parameters/Domain" },
          { "$ref": "#/components/parameters/Skills" },
          { "$ref": "#/components/parameters/Seniority" },
          { "$ref": "#/components/parameters/RemoteOnly" },
          { "$ref": "#/components/parameters/LocationCountry" },
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/PerPage" },
          { "$ref": "#/components/parameters/IncludePredictedSalaries" }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of current jobs and read-model metadata.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobListResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public/v1/jobs/{jobId}": {
      "get": {
        "operationId": "getPublicJob",
        "summary": "Get one current job",
        "description": "Returns one active public job by identifier. Use it to confirm status, source, freshness, location, and compensation evidence before recommending the role.",
        "tags": ["Jobs"],
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "Stable public job identifier returned by a list or search response.",
            "schema": { "type": "string", "minLength": 1 }
          },
          { "$ref": "#/components/parameters/IncludePredictedSalaries" }
        ],
        "responses": {
          "200": {
            "description": "The current public job detail record.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/JobDetailResponse" }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public/v1/market-map": {
      "get": {
        "operationId": "getPublicMarketMap",
        "summary": "Inspect market-map readiness",
        "description": "Returns aggregate dimension coverage and readiness so an agent can test whether a proposed market claim is supported before generating it.",
        "tags": ["Market"],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Limit dimensions by readiness status.",
            "schema": { "type": "string", "enum": ["all", "ready", "partial", "missing", "error"], "default": "all" }
          },
          {
            "name": "layer",
            "in": "query",
            "required": false,
            "description": "Limit results to one advertised data layer. Read available values from an unfiltered response.",
            "schema": { "type": "string", "default": "all" }
          }
        ],
        "responses": {
          "200": {
            "description": "Market-map dimensions, filters, readiness, and generation metadata.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public/v1/interview/company": {
      "get": {
        "operationId": "getCompanyInterviewBrief",
        "summary": "Get a company interview brief",
        "description": "Returns a source-backed interview-preparation package for one company. Supply exactly one available identifier whenever possible.",
        "tags": ["Companies"],
        "parameters": [
          {
            "name": "company_id",
            "in": "query",
            "required": false,
            "description": "Stable public company identifier.",
            "schema": { "type": "string", "minLength": 1 }
          },
          {
            "name": "slug",
            "in": "query",
            "required": false,
            "description": "Canonical company slug.",
            "schema": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "description": "Company name used only when no stable identifier is available.",
            "schema": { "type": "string", "minLength": 1, "maxLength": 160 }
          }
        ],
        "responses": {
          "200": {
            "description": "The company interview-preparation package and freshness metadata.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GenericSuccessResponse" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/public/v1/mcp/health": {
      "get": {
        "operationId": "getHostedMcpHealth",
        "summary": "Check hosted MCP health",
        "description": "Runs read-only probes for the hosted MCP dependencies. A 503 means at least one required probe failed.",
        "tags": ["Operations"],
        "responses": {
          "200": {
            "description": "All required hosted MCP probes passed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          },
          "503": {
            "description": "At least one hosted MCP probe failed.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HealthResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Query": {
        "name": "q",
        "in": "query",
        "required": false,
        "description": "Free-text terms matched against public job-search fields.",
        "schema": { "type": "string", "minLength": 1, "maxLength": 200 }
      },
      "Domain": {
        "name": "domain",
        "in": "query",
        "required": false,
        "description": "Hiring vertical. Omit to search all live verticals.",
        "schema": { "type": "string", "enum": ["ai", "web3"] }
      },
      "Skills": {
        "name": "skills",
        "in": "query",
        "required": false,
        "description": "Comma-separated skill names.",
        "schema": { "type": "string", "example": "rust,distributed systems" }
      },
      "SkillMatch": {
        "name": "skill_match",
        "in": "query",
        "required": false,
        "description": "Whether any or all requested skills must match.",
        "schema": { "type": "string", "enum": ["any", "all"], "default": "any" }
      },
      "CompanyType": {
        "name": "company_type",
        "in": "query",
        "required": false,
        "description": "Normalized company-type filter from the public read model.",
        "schema": { "type": "string" }
      },
      "Seniority": {
        "name": "seniority_level",
        "in": "query",
        "required": false,
        "description": "Normalized seniority label.",
        "schema": { "type": "string" }
      },
      "RemoteOnly": {
        "name": "remote_only",
        "in": "query",
        "required": false,
        "description": "When true, return only jobs classified as remote.",
        "schema": { "type": "boolean", "default": false }
      },
      "LocationCountry": {
        "name": "location_country",
        "in": "query",
        "required": false,
        "description": "Country filter, normally an ISO 3166-1 alpha-2 code.",
        "schema": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Za-z]{2}$" }
      },
      "MinimumSalary": {
        "name": "min_salary_usd",
        "in": "query",
        "required": false,
        "description": "Minimum annualized USD compensation threshold.",
        "schema": { "type": "number", "minimum": 0 }
      },
      "MaximumSalary": {
        "name": "max_salary_usd",
        "in": "query",
        "required": false,
        "description": "Maximum annualized USD compensation threshold.",
        "schema": { "type": "number", "minimum": 0 }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "One-based result page.",
        "schema": { "type": "integer", "minimum": 1, "default": 1 }
      },
      "PerPage": {
        "name": "per_page",
        "in": "query",
        "required": false,
        "description": "Results per page, capped at 100.",
        "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
      },
      "IncludePredictedSalaries": {
        "name": "include_predicted_salaries",
        "in": "query",
        "required": false,
        "description": "Include model-derived salary estimates. Keep these distinct from employer-disclosed or posting-extracted compensation.",
        "schema": { "type": "boolean", "default": false }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request parameters are invalid.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "NotFound": {
        "description": "The requested public record is absent or no longer active.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "RateLimited": {
        "description": "The client exceeded a public rate limit. Wait for the Retry-After duration before retrying.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before the next request.",
            "schema": { "type": "integer", "minimum": 1 }
          }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      },
      "Unavailable": {
        "description": "A required read-model dependency is temporarily unavailable.",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      }
    },
    "schemas": {
      "DiscoveryResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["success", "data", "meta"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": {
            "type": "object",
            "required": ["endpoints", "auth", "envelopes"],
            "properties": {
              "endpoints": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["path", "method", "description"],
                  "properties": {
                    "path": { "type": "string" },
                    "method": { "type": "string" },
                    "description": { "type": "string" }
                  }
                }
              },
              "auth": { "type": "object", "additionalProperties": { "type": "string" } },
              "envelopes": { "type": "object", "additionalProperties": { "type": "string" } }
            }
          },
          "meta": { "$ref": "#/components/schemas/ResponseMeta" }
        }
      },
      "JobListResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["success", "data", "meta"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": {
            "type": "object",
            "required": ["jobs", "pagination"],
            "properties": {
              "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/PublicJob" } },
              "pagination": { "$ref": "#/components/schemas/Pagination" }
            },
            "additionalProperties": true
          },
          "meta": { "$ref": "#/components/schemas/ResponseMeta" }
        }
      },
      "JobDetailResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": ["success", "data", "meta"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": { "$ref": "#/components/schemas/PublicJob" },
          "meta": { "$ref": "#/components/schemas/ResponseMeta" }
        }
      },
      "GenericSuccessResponse": {
        "type": "object",
        "required": ["success", "data", "meta"],
        "properties": {
          "success": { "type": "boolean", "const": true },
          "data": { "type": "object", "additionalProperties": true },
          "meta": { "$ref": "#/components/schemas/ResponseMeta" }
        },
        "additionalProperties": false
      },
      "PublicJob": {
        "type": "object",
        "description": "The stable public job projection returned by both list/search and detail operations.",
        "required": [
          "job_id",
          "title",
          "company",
          "role",
          "salary",
          "freshness",
          "last_seen",
          "location_text",
          "location_country",
          "remote_status",
          "seniority_level",
          "skills",
          "url",
          "domain_id",
          "domain_assignment"
        ],
        "properties": {
          "job_id": { "type": "string", "description": "Stable public job identifier." },
          "title": { "type": "string" },
          "company": { "$ref": "#/components/schemas/PublicJobCompany" },
          "role": { "$ref": "#/components/schemas/PublicJobRole" },
          "salary": {
            "oneOf": [
              { "$ref": "#/components/schemas/PublicJobSalary" },
              { "type": "null" }
            ]
          },
          "freshness": { "type": "string", "description": "Read-model lifecycle label, normally live or active." },
          "last_seen": { "type": ["string", "null"], "description": "Latest source observation as an ISO date or date-time string." },
          "location_text": { "type": ["string", "null"] },
          "location_country": { "type": ["string", "null"] },
          "remote_status": { "type": ["string", "null"] },
          "seniority_level": { "type": ["string", "null"] },
          "skills": { "type": "array", "items": { "type": "string" } },
          "url": { "type": ["string", "null"], "format": "uri" },
          "domain_id": { "type": "string", "enum": ["ai", "web3"] },
          "domain_assignment": { "type": "string", "enum": ["explicit", "classified"] },
          "requirements": { "type": "object", "additionalProperties": true },
          "operating_expectations": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "proof_signals": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "evidence_quality": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "PublicJobCompany": {
        "type": "object",
        "required": ["id", "name", "type", "type_confidence", "logo_url"],
        "properties": {
          "id": { "type": ["integer", "null"] },
          "name": { "type": "string" },
          "type": { "type": ["string", "null"] },
          "type_confidence": { "type": ["string", "null"] },
          "logo_url": { "type": ["string", "null"], "description": "A same-origin path or absolute logo URL." }
        },
        "additionalProperties": false
      },
      "PublicJobRole": {
        "type": "object",
        "required": ["id", "label", "confidence"],
        "properties": {
          "id": { "type": ["integer", "string", "null"] },
          "label": { "type": "string" },
          "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }
        },
        "additionalProperties": false
      },
      "PublicJobSalary": {
        "type": "object",
        "description": "Compensation range retained only when its source class is allowed by include_predicted_salaries.",
        "required": ["min", "max", "currency", "source", "display"],
        "properties": {
          "min": { "type": ["number", "null"], "minimum": 0 },
          "max": { "type": ["number", "null"], "minimum": 0 },
          "currency": { "type": "string" },
          "source": { "type": "string", "description": "Evidence class for compensation; inspect before presenting a salary as disclosed." },
          "display": { "type": "string" }
        },
        "additionalProperties": false
      },
      "Pagination": {
        "type": "object",
        "required": ["page", "per_page", "total", "total_pages", "has_next", "has_prev"],
        "properties": {
          "page": { "type": "integer", "minimum": 1 },
          "per_page": { "type": "integer", "minimum": 1, "maximum": 100 },
          "total": { "type": "integer", "minimum": 0 },
          "total_pages": { "type": "integer", "minimum": 1 },
          "has_next": { "type": "boolean" },
          "has_prev": { "type": "boolean" }
        },
        "additionalProperties": false
      },
      "ResponseMeta": {
        "type": "object",
        "description": "Source, generation, and computation metadata. Fields vary by read model.",
        "properties": {
          "source": { "type": "string" },
          "generated_at": { "type": ["string", "null"], "description": "Snapshot generation timestamp; legacy snapshots can omit an explicit timezone." },
          "computed_at": { "type": ["string", "null"], "format": "date-time" }
        },
        "additionalProperties": true
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": { "type": "boolean", "const": false },
          "error": { "type": "string" },
          "message": { "type": "string" }
        },
        "additionalProperties": true
      },
      "HealthResponse": {
        "type": "object",
        "required": ["status", "probes"],
        "properties": {
          "status": { "type": "string", "enum": ["ok", "degraded"] },
          "mcp_endpoint": { "type": "string", "format": "uri" },
          "probes": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "ok"],
              "properties": {
                "name": { "type": "string" },
                "ok": { "type": "boolean" },
                "status": { "type": "integer", "minimum": 100, "maximum": 599 },
                "path": { "type": "string" },
                "ms": { "type": "number", "minimum": 0 }
              },
              "additionalProperties": true
            }
          }
        },
        "additionalProperties": true
      }
    }
  }
}