{
  "openapi": "3.1.0",
  "info": {
    "title": "GhostPost.us Record API",
    "version": "2026-08-27",
    "summary": "Read-only access to the observation record a GhostPost.us workspace holds.",
    "description": "GhostPost.us is an outside-in evidence and observation layer — read-only middleware between configured public job sources and downstream compliance, HR, and legal systems. It delivers the record; it does not execute remediation. Coverage is limited to the sources configured and available for observation. Every endpoint is a read. Nothing here writes, charges, or mutates the record. A gp_test_ key returns fixed sample data marked mode:\"test\". Test data must never be stored, exported, or displayed alongside live workspace observations. GhostPost.us reports what the available public evidence shows — and clearly identifies what it cannot establish. GhostPost.us does not determine compliance, legal liability, intent, violations, or remediation requirements."
  },
  "x-evidence-states": [
    {
      "label": "Observed",
      "meaning": "Information GhostPost.us found and recorded in the public source at the time of observation."
    },
    {
      "label": "Stated absent",
      "meaning": "The reviewed source explicitly indicates that the information is not provided."
    },
    {
      "label": "Can't determine",
      "meaning": "The available public evidence does not allow GhostPost.us to determine the answer."
    },
    {
      "label": "Source unavailable",
      "meaning": "GhostPost.us could not lawfully access or successfully read the source. This is not treated as an absence."
    },
    {
      "label": "No requirement record identified",
      "meaning": "GhostPost.us does not currently have a sourced requirement record for this jurisdiction or topic in its regulatory dataset. This does not mean that no requirement exists, it does not mean the posting is compliant, and it does not mean there is no risk."
    },
    {
      "label": "Unverified",
      "meaning": "The requirement or data point has not yet been sufficiently verified against the required source and should not be treated as established fact."
    }
  ],
  "servers": [
    {
      "url": "/api/public/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "gp_live_… reads this workspace's record. gp_test_… reads sandbox data. Server-to-server only — never ship a key to a browser."
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "x-rate-limit": {
    "default": "120 requests per minute per key",
    "configurable": true
  },
  "paths": {
    "/": {
      "get": {
        "summary": "Discovery",
        "responses": {
          "200": {
            "description": "Service contract and endpoint index.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    },
    "/companies": {
      "get": {
        "summary": "Companies in this workspace's record",
        "responses": {
          "200": {
            "description": "Company list.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    },
    "/companies/{provider}/{account}": {
      "get": {
        "summary": "One employer source: evidence plus coverage",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "greenhouse",
                "lever",
                "ashby",
                "careers_page"
              ]
            }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Record for one source.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    },
    "/companies/{provider}/{account}/observations": {
      "get": {
        "summary": "Evidence — the observation history",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "greenhouse",
                "lever",
                "ashby",
                "careers_page"
              ]
            }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Timestamped, sourced observation history.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    },
    "/companies/{provider}/{account}/coverage": {
      "get": {
        "summary": "Monitor — each recorded read attempt",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "greenhouse",
                "lever",
                "ashby",
                "careers_page"
              ]
            }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Attempts and their outcomes. Unread is never an absence.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    },
    "/companies/{provider}/{account}/changes": {
      "get": {
        "summary": "Watch — what changed between observations",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "greenhouse",
                "lever",
                "ashby",
                "careers_page"
              ]
            }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Change lines, newest first.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    },
    "/requirements": {
      "get": {
        "summary": "Requirements — records held for named jurisdictions",
        "parameters": [
          {
            "name": "jurisdiction",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Requirement records. Applicability is not decided here.",
            "headers": {
              "X-GhostPost.us-Request-Id": {
                "schema": {
                  "type": "string"
                },
                "description": "Cite this in support."
              },
              "X-GhostPost.us-Mode": {
                "schema": {
                  "type": "string",
                  "enum": [
                    "live",
                    "test"
                  ]
                },
                "description": "test responses are fixed sample data, never a real observation."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid key."
          },
          "404": {
            "description": "This workspace holds no record for that source."
          },
          "429": {
            "description": "Operating limit exceeded. Retry-After is set."
          }
        }
      }
    }
  }
}