{
  "openapi": "3.1.0",
  "info": {
    "title": "High Signal Podcasts public evidence API",
    "version": "1.0.0",
    "description": "Unauthenticated read-only access to trusted published claims, people, sources, and source-linked recommendations. Shows with unresolved speaker attribution are withheld, and missing evidence is returned as missing."
  },
  "servers": [{ "url": "https://api.podcasts.highsignal.app" }],
  "paths": {
    "/api/stats": {
      "get": {
        "operationId": "getCorpusStats",
        "summary": "Get public corpus counts",
        "responses": { "200": { "description": "Current counts of people, episodes, published claims, and references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Stats" } } } } }
      }
    },
    "/api/people": {
      "get": {
        "operationId": "listPeople",
        "summary": "List active people with published claims",
        "parameters": [
          { "name": "q", "in": "query", "description": "Case-insensitive person, title, or organization match", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": { "200": { "description": "People with public evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleResponse" } } } } }
      }
    },
    "/api/people/{slug}": {
      "get": {
        "operationId": "getPersonEvidence",
        "summary": "Get one person with published claims and recommendations",
        "parameters": [{ "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Person, claims, and recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersonEvidenceResponse" } } } },
          "404": { "description": "No active person found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/claims/{id}": {
      "get": {
        "operationId": "getPublishedClaim",
        "summary": "Get one published claim with evidence, actionable references, and optional transcript context",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "context", "in": "query", "description": "Set to 1 to include the stored transcript around the quote. Omitted by default so the ordinary receipt reads no transcript.", "schema": { "type": "string", "enum": ["1", "true"] } }
        ],
        "responses": {
          "200": { "description": "Published claim, evidence, and references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimEvidenceResponse" } } } },
          "404": { "description": "No published claim found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/sources": {
      "get": {
        "operationId": "listSources",
        "summary": "List source episodes with published claims",
        "parameters": [
          { "name": "q", "in": "query", "description": "Case-insensitive episode or publisher match", "schema": { "type": "string" } },
          { "name": "show", "in": "query", "description": "Publisher show slug", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": { "200": { "description": "Trusted source episodes and total count", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcesResponse" } } } } }
      }
    },
    "/api/sources/{id}": {
      "get": {
        "operationId": "getSourceEvidence",
        "summary": "Get one source episode and its published claims",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": { "description": "Source and published claims", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceEvidenceResponse" } } } },
          "404": { "description": "Source not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchPublishedClaims",
        "summary": "Search and filter published claims",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "person", "in": "query", "description": "Person slug", "schema": { "type": "string" } },
          { "name": "type", "in": "query", "schema": { "type": "string" } },
          { "name": "topic", "in": "query", "description": "Topic slug", "schema": { "type": "string" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": { "200": { "description": "Published claims or an explicit insufficient-evidence result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimsResponse" } } } } }
      }
    },
    "/api/recommendations": {
      "get": {
        "operationId": "listPublishedRecommendations",
        "summary": "List source-linked recommendations and uses",
        "parameters": [
          { "name": "person", "in": "query", "description": "Person slug", "schema": { "type": "string" } },
          { "name": "kind", "in": "query", "description": "Reference kind such as book, tool, or product", "schema": { "type": "string" } },
          { "name": "role", "in": "query", "description": "Evidence role: recommends, uses, likes, owns, built, or avoids", "schema": { "type": "string" } },
          { "name": "name", "in": "query", "description": "Canonicalized exact item name", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Published references or an explicit insufficient-evidence result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationsResponse" } } } } }
      }
    },
    "/api/recommendation-groups": {
      "get": {
        "operationId": "listGroupedRecommendations",
        "summary": "Group named references by distinct attributable people",
        "parameters": [
          { "name": "q", "in": "query", "description": "Case-insensitive named-item match", "schema": { "type": "string" } },
          { "name": "kind", "in": "query", "description": "Reference kind such as book, app, tool, or service", "schema": { "type": "string" } },
          { "name": "role", "in": "query", "description": "Evidence role: recommends, uses, likes, owns, built, or avoids", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } },
          { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } }
        ],
        "responses": { "200": { "description": "Named reference groups ranked by distinct people, or an explicit insufficient-evidence result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendationGroupsResponse" } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": { "error": { "type": "string" } },
        "additionalProperties": true
      },
      "Person": {
        "type": "object",
        "required": ["id", "name", "slug", "status"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "status": { "type": "string", "enum": ["active", "hidden"] },
          "title": { "type": ["string", "null"] },
          "org": { "type": ["string", "null"] },
          "bio": { "type": ["string", "null"] },
          "claimCount": { "type": "integer", "minimum": 0 },
          "sourceCount": { "type": "integer", "minimum": 0 }
        },
        "additionalProperties": true
      },
      "Claim": {
        "type": "object",
        "required": ["id", "personId", "episodeId", "assertion", "quote", "claimType", "reviewStatus"],
        "properties": {
          "id": { "type": "string" },
          "personId": { "type": "string" },
          "episodeId": { "type": "string" },
          "assertion": { "type": "string" },
          "quote": { "type": "string" },
          "claimType": { "type": "string" },
          "reviewStatus": { "type": "string" },
          "stance": { "type": ["string", "null"] },
          "saidOn": { "type": ["string", "null"], "format": "date-time" },
          "timestampS": { "type": ["number", "null"] },
          "personName": { "type": "string" },
          "personSlug": { "type": "string" },
          "personTitle": { "type": ["string", "null"] },
          "personOrg": { "type": ["string", "null"] },
          "episodeTitle": { "type": "string" },
          "showName": { "type": "string" },
          "showSlug": { "type": "string" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "deepLinkUrl": { "type": ["string", "null"], "format": "uri" }
        },
        "additionalProperties": true
      },
      "Source": {
        "type": "object",
        "required": ["id", "showId", "title", "status"],
        "properties": {
          "id": { "type": "string" },
          "showId": { "type": "string" },
          "title": { "type": "string" },
          "status": { "type": "string" },
          "publishedAt": { "type": ["string", "null"], "format": "date-time" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "showName": { "type": "string" },
          "showSlug": { "type": "string" },
          "claimCount": { "type": "integer", "minimum": 0 },
          "peopleCount": { "type": "integer", "minimum": 0 }
        },
        "additionalProperties": true
      },
      "Recommendation": {
        "type": "object",
        "required": ["claimId", "personId", "personName", "name", "kind", "role", "assertion", "quote"],
        "properties": {
          "claimId": { "type": "string" },
          "personId": { "type": "string" },
          "personName": { "type": "string" },
          "name": { "type": "string" },
          "kind": { "type": "string" },
          "role": { "type": "string" },
          "assertion": { "type": "string" },
          "quote": { "type": "string" },
          "deepLinkUrl": { "type": ["string", "null"], "format": "uri" },
          "sourceUrl": { "type": ["string", "null"], "format": "uri" },
          "episodeTitle": { "type": "string" },
          "showName": { "type": "string" },
          "saidOn": { "type": ["string", "null"], "format": "date-time" },
          "timestampS": { "type": ["number", "null"] }
        },
        "additionalProperties": true
      },
      "RecommendationGroup": {
        "type": "object",
        "required": ["kind", "name", "occurrenceCount", "peopleCount", "roleCounts"],
        "properties": {
          "kind": { "type": "string" },
          "name": { "type": "string" },
          "occurrenceCount": { "type": "integer", "minimum": 1 },
          "peopleCount": { "type": "integer", "minimum": 1 },
          "roleCounts": {
            "type": "object",
            "required": ["recommends", "uses", "likes", "owns", "built", "avoids"],
            "properties": {
              "recommends": { "type": "integer", "minimum": 0 },
              "uses": { "type": "integer", "minimum": 0 },
              "likes": { "type": "integer", "minimum": 0 },
              "owns": { "type": "integer", "minimum": 0 },
              "built": { "type": "integer", "minimum": 0 },
              "avoids": { "type": "integer", "minimum": 0 }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      },
      "Stats": {
        "type": "object",
        "required": ["people", "episodes", "publishedClaims", "publishedReferences", "catalogEpisodes", "transcriptEpisodes", "trustedShows", "trustPolicy"],
        "properties": {
          "people": { "type": "integer", "minimum": 0 },
          "episodes": { "type": "integer", "minimum": 0 },
          "publishedClaims": { "type": "integer", "minimum": 0 },
          "publishedReferences": { "type": "integer", "minimum": 0 },
          "catalogEpisodes": { "type": "integer", "minimum": 0 },
          "transcriptEpisodes": { "type": "integer", "minimum": 0 },
          "trustedShows": { "type": "integer", "minimum": 0 },
          "trustPolicy": {
            "type": "object",
            "required": ["withheldShows", "wording"],
            "properties": {
              "withheldShows": { "type": "integer", "minimum": 0 },
              "wording": { "type": "string" }
            }
          }
        }
      },
      "PeopleResponse": {
        "type": "object",
        "required": ["people", "total"],
        "properties": {
          "people": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } },
          "total": { "type": "integer", "minimum": 0 }
        }
      },
      "ClaimsResponse": {
        "type": "object",
        "required": ["claims"],
        "properties": {
          "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } },
          "evidence": { "type": "string", "enum": ["insufficient"] }
        }
      },
      "RecommendationsResponse": {
        "type": "object",
        "required": ["recommendations"],
        "properties": {
          "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } },
          "evidence": { "type": "string", "enum": ["insufficient"] }
        }
      },
      "RecommendationGroupsResponse": {
        "type": "object",
        "required": ["groups", "total"],
        "properties": {
          "groups": { "type": "array", "items": { "$ref": "#/components/schemas/RecommendationGroup" } },
          "total": { "type": "integer", "minimum": 0 },
          "evidence": { "type": "string", "enum": ["insufficient"] }
        }
      },
      "PersonEvidenceResponse": {
        "type": "object",
        "required": ["person", "claims", "recommendations"],
        "properties": {
          "person": { "$ref": "#/components/schemas/Person" },
          "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } },
          "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/Recommendation" } }
        }
      },
      "ClaimEvidenceResponse": {
        "type": "object",
        "required": ["claim", "evidence", "references"],
        "properties": {
          "claim": { "$ref": "#/components/schemas/Claim" },
          "context": { "type": ["object", "null"], "description": "Stored transcript around the verbatim quote, returned only for context=1. Null when the stored transcript is missing or the quote cannot be anchored in it; context is never generated.", "required": ["text", "quoteStart", "quoteEnd"], "properties": { "text": { "type": "string" }, "quoteStart": { "type": "integer" }, "quoteEnd": { "type": "integer" } } },
          "evidence": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "references": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      },
      "SourcesResponse": {
        "type": "object",
        "required": ["publishers", "sources", "total"],
        "properties": {
          "publishers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["name", "slug"],
              "properties": { "name": { "type": "string" }, "slug": { "type": "string" } }
            }
          },
          "sources": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } },
          "total": { "type": "integer", "minimum": 0 }
        }
      },
      "SourceEvidenceResponse": {
        "type": "object",
        "required": ["source", "claims"],
        "properties": {
          "source": { "$ref": "#/components/schemas/Source" },
          "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }
        }
      }
    }
  }
}