openapi: 3.1.0
info:
  title: Osmaura Prospect API
  version: 2.0.0
  description: >-
    Retrieve tenant-scoped, human-reviewed prospect editions. Version 2 keeps
    source-backed data separate from analyst conclusions and includes source
    coverage, official links, and reproducible record locators. Only explicitly
    published editions are visible.
servers:
  - url: https://dashboard.osmaura.com
security:
  - bearerAuth: []
paths:
  /v2/prospects:
    get:
      operationId: getProspects
      summary: Get a published prospect edition
      description: >-
        Returns the latest complete prospect edition unless a date is supplied.
        Dossiers are returned inline and rank is analysis.ranking.rank.
      parameters:
        - $ref: "#/components/parameters/EditionDate"
        - $ref: "#/components/parameters/IfNoneMatch"
      responses:
        "200":
          description: Published prospect edition.
          headers:
            ETag:
              schema: {type: string}
            Cache-Control:
              schema: {type: string, example: "private, max-age=300"}
          content:
            application/json:
              schema: {$ref: "#/components/schemas/ProspectEdition"}
        "304": {description: The edition has not changed.}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/SubscriptionRequired"}
        "404": {$ref: "#/components/responses/NotFound"}
        "503": {$ref: "#/components/responses/Unavailable"}
  /v2/prospect-editions:
    get:
      operationId: listProspectEditions
      summary: List published prospect-edition history
      parameters:
        - $ref: "#/components/parameters/EditionLimit"
      responses:
        "200":
          description: Published editions, newest first.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [editions]
                properties:
                  editions:
                    type: array
                    items: {$ref: "#/components/schemas/EditionSummary"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/SubscriptionRequired"}
        "503": {$ref: "#/components/responses/Unavailable"}
  /v1/signals:
    get:
      deprecated: true
      operationId: getLegacySignals
      summary: Get a compact legacy signal edition
      description: Existing integrations may continue using this endpoint.
      parameters:
        - $ref: "#/components/parameters/EditionDate"
        - $ref: "#/components/parameters/IfNoneMatch"
      responses:
        "200":
          description: Published compact signal edition.
          content:
            application/json:
              schema: {$ref: "#/components/schemas/LegacyEdition"}
        "304": {description: The edition has not changed.}
        "400": {$ref: "#/components/responses/BadRequest"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/SubscriptionRequired"}
        "404": {$ref: "#/components/responses/NotFound"}
        "503": {$ref: "#/components/responses/Unavailable"}
  /v1/signal-editions:
    get:
      deprecated: true
      operationId: listLegacySignalEditions
      summary: List compact legacy edition history
      parameters:
        - $ref: "#/components/parameters/EditionLimit"
      responses:
        "200":
          description: Published editions, newest first.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required: [editions]
                properties:
                  editions:
                    type: array
                    items: {$ref: "#/components/schemas/EditionSummary"}
        "401": {$ref: "#/components/responses/Unauthorized"}
        "402": {$ref: "#/components/responses/SubscriptionRequired"}
        "503": {$ref: "#/components/responses/Unavailable"}
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Tenant-scoped production read key.
  parameters:
    EditionDate:
      name: date
      in: query
      required: false
      description: Edition date in YYYY-MM-DD format.
      schema: {type: string, format: date}
    IfNoneMatch:
      name: If-None-Match
      in: header
      required: false
      schema: {type: string}
    EditionLimit:
      name: limit
      in: query
      required: false
      schema: {type: integer, minimum: 1, maximum: 90, default: 30}
  responses:
    BadRequest:
      description: Invalid request.
      content: {application/json: {schema: {$ref: "#/components/schemas/Error"}}}
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content: {application/json: {schema: {$ref: "#/components/schemas/Error"}}}
    SubscriptionRequired:
      description: An active organization subscription is required.
      content: {application/json: {schema: {$ref: "#/components/schemas/Error"}}}
    NotFound:
      description: No published edition exists for the requested date.
      content: {application/json: {schema: {$ref: "#/components/schemas/Error"}}}
    Unavailable:
      description: Account-access verification is temporarily unavailable.
      content: {application/json: {schema: {$ref: "#/components/schemas/Error"}}}
  schemas:
    ProspectEdition:
      type: object
      additionalProperties: false
      required: [object, schema_version, edition_date, revision, published_at, count, prospects]
      properties:
        object: {type: string, const: prospect_edition}
        schema_version: {type: string, const: "2.0"}
        edition_date: {type: string, format: date}
        revision: {type: integer, minimum: 1}
        published_at: {type: string, format: date-time}
        count: {type: integer, minimum: 1, maximum: 100}
        prospects:
          type: array
          minItems: 1
          maxItems: 100
          items: {$ref: "#/components/schemas/ProspectDossier"}
    EditionSummary:
      type: object
      additionalProperties: false
      required: [edition_date, published_at, revision, count]
      properties:
        edition_date: {type: string, format: date}
        published_at: {type: string, format: date-time}
        revision: {type: integer, minimum: 1}
        count: {type: integer, minimum: 1, maximum: 100}
    ProspectDossier:
      type: object
      additionalProperties: false
      description: >-
        The five-field prospect contract. Observed facts and deterministic
        statistics live under data; interpretation lives under analysis.
      required: [id, prospect, data, analysis, coverage]
      properties:
        id: {type: string, minLength: 1}
        prospect: {$ref: "#/components/schemas/ProspectIdentity"}
        data: {$ref: "#/components/schemas/ProspectData"}
        analysis: {$ref: "#/components/schemas/ProspectAnalysis"}
        coverage: {$ref: "#/components/schemas/Coverage"}
    ProspectIdentity:
      type: object
      additionalProperties: false
      required: [type, name, legal_names, domain, locations, identifiers, current_employment]
      properties:
        type: {enum: [organization, person]}
        name: {type: string, minLength: 1}
        legal_names:
          type: array
          items: {type: string}
        domain: {type: [string, "null"]}
        locations:
          type: array
          items: {$ref: "#/components/schemas/Location"}
        identifiers:
          type: object
          description: Source and warehouse identifiers; unknown values are null.
          additionalProperties: true
        current_employment:
          oneOf:
            - {type: "null"}
            - {$ref: "#/components/schemas/CurrentEmployment"}
    Location:
      type: object
      additionalProperties: false
      required: [city, state, country]
      properties:
        city: {type: [string, "null"]}
        state: {type: [string, "null"]}
        country: {type: [string, "null"]}
    CurrentEmployment:
      type: object
      additionalProperties: false
      required: [employer, role, location]
      properties:
        employer: {type: [string, "null"]}
        role: {type: [string, "null"]}
        location: {type: [string, "null"]}
    ProspectData:
      type: object
      description: >-
        Source data and deterministic statistics grouped by real-world domain.
        Empty arrays do not imply a checked no-match; consult coverage.sources.
      additionalProperties: true
      required: [dol_oflc, uscis, dhs, government_business, company, contacts]
      properties:
        dol_oflc: {$ref: "#/components/schemas/DolData"}
        uscis:
          type: object
          additionalProperties: true
          required: [h1b_employer_hub]
          properties:
            h1b_employer_hub: {$ref: "#/components/schemas/DataCollection"}
        dhs:
          type: object
          additionalProperties: true
          required: [everify]
          properties:
            everify: {$ref: "#/components/schemas/DataCollection"}
        government_business: {$ref: "#/components/schemas/GovernmentBusinessData"}
        company: {$ref: "#/components/schemas/CompanyData"}
        professional: {$ref: "#/components/schemas/ProfessionalData"}
        contacts:
          type: array
          items: {$ref: "#/components/schemas/Contact"}
    DolData:
      type: object
      additionalProperties: true
      required: [lca, perm, pwd]
      properties:
        lca: {$ref: "#/components/schemas/DataCollection"}
        perm: {$ref: "#/components/schemas/DataCollection"}
        pwd: {$ref: "#/components/schemas/DataCollection"}
    DataCollection:
      type: object
      additionalProperties: true
      description: A source-specific record collection and its deterministic aggregates.
      properties:
        statistics:
          type: object
          additionalProperties: true
        by_fiscal_year:
          type: array
          items: {type: object, additionalProperties: true}
        records:
          type: array
          items: {$ref: "#/components/schemas/FactualRecord"}
        source: {$ref: "#/components/schemas/Source"}
    GovernmentBusinessData:
      type: object
      additionalProperties: true
      properties:
        sec_filings: {$ref: "#/components/schemas/FactualRecordArray"}
        contracts: {$ref: "#/components/schemas/FactualRecordArray"}
        grants: {$ref: "#/components/schemas/FactualRecordArray"}
        trademarks: {$ref: "#/components/schemas/FactualRecordArray"}
        corporate_records: {$ref: "#/components/schemas/FactualRecordArray"}
        regulatory_records: {$ref: "#/components/schemas/FactualRecordArray"}
        warn_notices: {$ref: "#/components/schemas/FactualRecordArray"}
        enforcement: {$ref: "#/components/schemas/FactualRecordArray"}
    CompanyData:
      type: object
      additionalProperties: true
      properties:
        funding_events: {$ref: "#/components/schemas/FactualRecordArray"}
        recent_developments: {$ref: "#/components/schemas/FactualRecordArray"}
        job_postings: {$ref: "#/components/schemas/FactualRecordArray"}
        locations: {$ref: "#/components/schemas/FactualRecordArray"}
        reported_metrics: {$ref: "#/components/schemas/FactualRecordArray"}
    ProfessionalData:
      type: object
      additionalProperties: true
      description: Present for person prospects when relevant.
      properties:
        employment: {$ref: "#/components/schemas/FactualRecordArray"}
        education: {$ref: "#/components/schemas/FactualRecordArray"}
        publications: {$ref: "#/components/schemas/FactualRecordArray"}
        patents: {$ref: "#/components/schemas/FactualRecordArray"}
        open_source: {$ref: "#/components/schemas/FactualRecordArray"}
        awards: {$ref: "#/components/schemas/FactualRecordArray"}
        judging_and_review: {$ref: "#/components/schemas/FactualRecordArray"}
        standards: {$ref: "#/components/schemas/FactualRecordArray"}
        speaking: {$ref: "#/components/schemas/FactualRecordArray"}
        media: {$ref: "#/components/schemas/FactualRecordArray"}
    FactualRecordArray:
      type: array
      items: {$ref: "#/components/schemas/FactualRecord"}
    FactualRecord:
      type: object
      additionalProperties: true
      required: [id, source]
      properties:
        id: {type: string, minLength: 1}
        source: {$ref: "#/components/schemas/Source"}
    Source:
      type: object
      additionalProperties: true
      required: [publisher, official_page_url, record_locator, retrieved_at]
      properties:
        publisher: {type: string, minLength: 1}
        official_page_url: {type: string, format: uri}
        dataset:
          oneOf:
            - {type: "null"}
            - {$ref: "#/components/schemas/Dataset"}
        record_locator:
          type: object
          additionalProperties: true
        retrieved_at: {type: string, format: date-time}
    Dataset:
      type: object
      additionalProperties: false
      required: [filename, download_url, record_layout_url, data_through]
      properties:
        filename: {type: [string, "null"]}
        download_url: {type: [string, "null"], format: uri}
        record_layout_url: {type: [string, "null"], format: uri}
        data_through: {type: [string, "null"], format: date}
    Contact:
      type: object
      additionalProperties: false
      required: [id, name, role, channels, evidence_ids]
      properties:
        id: {type: string, minLength: 1}
        name: {type: string, minLength: 1}
        role: {type: [string, "null"]}
        channels:
          type: array
          items: {$ref: "#/components/schemas/ContactChannel"}
        evidence_ids:
          type: array
          items: {type: string}
    ContactChannel:
      type: object
      additionalProperties: false
      required: [type, value, source_url, as_of, current_status, outreach_suitability, consent_status, suppression_reason]
      properties:
        type: {enum: [email, phone, linkedin, github, company_form, other]}
        value: {type: [string, "null"]}
        source_url: {type: [string, "null"], format: uri}
        as_of: {type: [string, "null"], format: date}
        current_status: {enum: [verified_current, verified_historical, unverified, unknown]}
        outreach_suitability: {enum: [ready, permission_first, identity_only, suppress]}
        consent_status: {enum: [consented, unknown, not_applicable, opted_out]}
        suppression_reason: {type: [string, "null"]}
    ProspectAnalysis:
      type: object
      additionalProperties: false
      required:
        - generated_at
        - analysis_version
        - ranking
        - summary
        - why_now
        - counsel_analysis
        - lead_factors
        - counterevidence
        - context_only
        - recommended_approach
        - limitations
        - evidence_accounting
      properties:
        generated_at: {type: string, format: date-time}
        analysis_version: {type: string, minLength: 1}
        ranking: {$ref: "#/components/schemas/Ranking"}
        summary: {type: string, minLength: 1}
        why_now: {$ref: "#/components/schemas/WhyNow"}
        counsel_analysis: {$ref: "#/components/schemas/CounselAnalysis"}
        lead_factors:
          type: array
          items: {$ref: "#/components/schemas/AnalysisFinding"}
        counterevidence:
          type: array
          items: {$ref: "#/components/schemas/AnalysisFinding"}
        context_only:
          type: array
          items: {$ref: "#/components/schemas/AnalysisFinding"}
        recommended_approach: {$ref: "#/components/schemas/RecommendedApproach"}
        eligibility_screen:
          type: [object, "null"]
          additionalProperties: true
          description: Evidence screen only; never a legal conclusion.
        limitations:
          type: array
          items: {type: string}
        evidence_accounting: {$ref: "#/components/schemas/EvidenceAccounting"}
    Ranking:
      type: object
      additionalProperties: false
      required: [rank, disposition, disposition_reason, scores, confidence]
      properties:
        rank: {type: integer, minimum: 1}
        disposition: {enum: [qualified, nurture, monitor, suppress]}
        disposition_reason: {type: string, minLength: 1}
        scores: {$ref: "#/components/schemas/Scores"}
        confidence: {type: number, minimum: 0, maximum: 1}
    Scores:
      type: object
      additionalProperties: false
      required: [evidence_strength, why_now_strength, commercial_readiness, counsel_opportunity, mobility_intent, overall_rank]
      properties:
        evidence_strength: {type: number, minimum: 0, maximum: 100}
        why_now_strength: {type: number, minimum: 0, maximum: 100}
        commercial_readiness: {type: number, minimum: 0, maximum: 100}
        counsel_opportunity: {type: [number, "null"], minimum: 0, maximum: 100}
        mobility_intent: {type: [number, "null"], minimum: 0, maximum: 100}
        overall_rank: {type: number, minimum: 0, maximum: 100}
    WhyNow:
      type: object
      additionalProperties: false
      required: [narrative, trigger_date, urgency_window, evidence_ids]
      properties:
        narrative: {type: string, minLength: 1}
        trigger_date: {type: [string, "null"], format: date}
        urgency_window: {type: string, minLength: 1}
        evidence_ids:
          type: array
          items: {type: string}
    CounselAnalysis:
      type: object
      additionalProperties: false
      required: [classification, narrative, scope, filings_reviewed, named_counsel_filings, confidence, evidence_ids, caveat]
      properties:
        classification:
          enum: [observed_pro_se, no_named_counsel, incumbent_identified, fragmented_or_transitioning, possible_undisclosed_adviser, unknown, not_applicable]
        narrative: {type: string, minLength: 1}
        scope: {$ref: "#/components/schemas/CounselScope"}
        filings_reviewed: {type: [integer, "null"], minimum: 0}
        named_counsel_filings: {type: [integer, "null"], minimum: 0}
        confidence: {type: number, minimum: 0, maximum: 1}
        evidence_ids:
          type: array
          items: {type: string}
        caveat: {type: string, minLength: 1}
    CounselScope:
      type: object
      additionalProperties: false
      required: [programs, from, through]
      properties:
        programs:
          type: array
          items: {type: string}
        from: {type: [string, "null"], format: date}
        through: {type: [string, "null"], format: date}
    AnalysisFinding:
      type: object
      additionalProperties: false
      required: [finding, effect_on_lead, explanation, strength, evidence_ids]
      properties:
        finding: {type: string, minLength: 1}
        effect_on_lead: {enum: [supports, weakens, limits_inference, context]}
        explanation: {type: string, minLength: 1}
        strength: {enum: [strong, moderate, weak, contextual]}
        evidence_ids:
          type: array
          items: {type: string}
    RecommendedApproach:
      type: object
      additionalProperties: false
      required: [narrative, recommended_contact_id]
      properties:
        narrative: {type: string, minLength: 1}
        recommended_contact_id: {type: [string, "null"]}
    EvidenceAccounting:
      type: object
      additionalProperties: false
      required:
        - records_reviewed
        - records_supporting_lead
        - records_weakening_lead
        - records_providing_context_only
        - records_used_for_identity_or_contact
        - unaddressed_record_ids
      properties:
        records_reviewed: {type: integer, minimum: 0}
        records_supporting_lead: {type: integer, minimum: 0}
        records_weakening_lead: {type: integer, minimum: 0}
        records_providing_context_only: {type: integer, minimum: 0}
        records_used_for_identity_or_contact: {type: integer, minimum: 0}
        unaddressed_record_ids:
          type: array
          items: {type: string}
    Coverage:
      type: object
      additionalProperties: false
      required: [generated_at, data_through, sources, identity_warnings, known_gaps]
      properties:
        generated_at: {type: string, format: date-time}
        data_through: {type: string, format: date}
        sources:
          type: array
          items: {$ref: "#/components/schemas/SourceCoverage"}
        identity_warnings:
          type: array
          items: {type: string}
        known_gaps:
          type: array
          items: {type: string}
    SourceCoverage:
      type: object
      additionalProperties: false
      required: [source, status, data_through, checked_at, record_count, query, limitations]
      properties:
        source: {type: string, minLength: 1}
        status: {enum: [matched, checked_no_match, not_applicable, not_checked, source_unavailable]}
        data_through: {type: [string, "null"], format: date}
        checked_at: {type: [string, "null"], format: date-time}
        record_count: {type: [integer, "null"], minimum: 0}
        query:
          type: object
          additionalProperties: true
        limitations:
          type: array
          items: {type: string}
    LegacyEdition:
      type: object
      additionalProperties: false
      required: [object, edition_date, revision, published_at, count, signals]
      properties:
        object: {type: string, const: signal_edition}
        edition_date: {type: string, format: date}
        revision: {type: integer, minimum: 1}
        published_at: {type: string, format: date-time}
        count: {type: integer, minimum: 1, maximum: 100}
        signals:
          type: array
          items: {$ref: "#/components/schemas/LegacySignal"}
    LegacySignal:
      type: object
      additionalProperties: true
      required: [id, rank, type, company, rationale, contacts, evidence]
      properties:
        id: {type: string}
        rank: {type: integer, minimum: 1}
        type: {type: string}
        company: {type: object, additionalProperties: true}
        rationale: {type: object, additionalProperties: true}
        contacts: {type: array, items: {type: object, additionalProperties: true}}
        evidence: {type: array, items: {type: object, additionalProperties: true}}
    Error:
      type: object
      additionalProperties: false
      required: [error]
      properties:
        error:
          type: object
          additionalProperties: false
          required: [code, message]
          properties:
            code: {type: string}
            message: {type: string}