HitApply Internal API

openapi: 3.2.0
info:
  title: Fast Internal API
  version: 0.1.0
tags:
- name: Internal
paths:
  /v1/internal/discoveries:
    post:
      summary: Internal Discoveries
      description: 'First-party ingest, both versions.


        One route rather than two because everything below the envelope is identical: the same jobs, the

        same pool identity, the same canonicalization and matching in the same transaction. What v2

        changes is who is asking (a per-connector token, not the shared one), what the jobs belong to (a

        target run), and how the answer is worded.'
      operationId: internal_discoveries_v1_internal_discoveries_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HostedBatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/description-enrichment/claim:
    post:
      summary: Claim Description Enrichment
      operationId: claim_description_enrichment_v1_internal_description_enrichment_claim_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentClaimBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/description-enrichment/complete:
    post:
      summary: Complete Description Enrichment
      operationId: complete_description_enrichment_v1_internal_description_enrichment_complete_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichmentCompleteBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/job-classification/claim:
    post:
      summary: Claim Job Classification
      operationId: claim_job_classification_v1_internal_job_classification_claim_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassificationClaimBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/job-classification/complete:
    post:
      summary: Complete Job Classification
      operationId: complete_job_classification_v1_internal_job_classification_complete_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClassificationCompleteBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/connectors/{connector_key}/config:
    get:
      summary: Internal Connector Config
      description: 'A connector''s config poll, which doubles as its heartbeat and health report.


        Three jobs, one round-trip: the upsert below is the only liveness signal we

        have for a connector that is running fine but currently finding nothing.


        `status` carries last cycle''s outcome — `ok`, or a short summary of which

        sources failed. Liveness alone can''t see that: a connector whose source API

        is rejecting its key keeps polling perfectly happily.


        An *absent* `status` means "this build can''t report", not "healthy", so it

        leaves the stored value alone rather than inventing an all-clear. Only an

        explicit `ok` clears it.


        `enabled` is advisory: it asks, and a well-behaved connector skips its

        scrape, but the process stays up either way and a connector we don''t control

        would ignore it — which is why the ingest token remains the real boundary.

        Actually stopping a process is done on the VM with systemctl.'
      operationId: internal_connector_config_v1_internal_connectors__connector_key__config_get
      parameters:
      - name: connector_key
        in: path
        required: true
        schema:
          type: string
          title: Connector Key
      - name: version
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Version
      - name: status
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Status
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/connectors/{connector_key}/poll:
    post:
      summary: Internal Connector Poll
      description: 'The target poll: heartbeat in, full target snapshot out.


        The response is always the complete eligible set, never a delta. That is a deliberate trade: a

        delta would need a per-connector cursor, reconciliation of adds against removes, and a disk

        cache on the connector whose correctness would need its own protocol and its own bugs. A full

        snapshot is idempotent, and a connector that misses one poll is simply one cycle stale.


        `last_cycle` is an aggregate and nothing else. Per-target detail goes to the target-run route,

        where it is structured; accepting free text here is how an API key ends up in a database column.'
      operationId: internal_connector_poll_v1_internal_connectors__connector_key__poll_post
      parameters:
      - name: connector_key
        in: path
        required: true
        schema:
          type: string
          title: Connector Key
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PollBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /v1/internal/connectors/{connector_key}/target-runs:
    post:
      summary: Internal Connector Target Run
      description: 'Record one connector''s attempt at one target. Replay-safe on `run_id`.


        A connector reports a run only once every chunk of it is acknowledged, and it retries the report

        if that fails — so the same run_id arriving twice is the normal case, not an error. It is the

        connector''s ID: HitApply neither leases runs nor schedules them.


        The target_id is stored without checking that it still exists. A snapshot is a moment in time,

        and a target can lose its last reference mid-cycle; refusing the report would lose the record of

        work that genuinely happened, to protect a foreign key nobody reads through.'
      operationId: internal_connector_target_run_v1_internal_connectors__connector_key__target_runs_post
      parameters:
      - name: connector_key
        in: path
        required: true
        schema:
          type: string
          title: Connector Key
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          default: ''
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TargetRunBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
components:
  schemas:
    LastCycle:
      properties:
        status:
          type: string
          title: Status
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        targets_succeeded:
          type: integer
          title: Targets Succeeded
          default: 0
        targets_failed:
          type: integer
          title: Targets Failed
          default: 0
      type: object
      required:
      - status
      title: LastCycle
    ClassificationResultBody:
      properties:
        job_id:
          type: string
          title: Job Id
        response:
          anyOf:
          - type: string
            maxLength: 20000
          - type: 'null'
          title: Response
        error:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Error
      type: object
      required:
      - job_id
      title: ClassificationResultBody
    EnrichmentClaimBody:
      properties:
        limit:
          type: integer
          title: Limit
          default: 5
      type: object
      title: EnrichmentClaimBody
    HostedConnector:
      properties:
        key:
          type: string
          title: Key
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        runtime_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Runtime Version
        revision:
          anyOf:
          - type: string
          - type: 'null'
          title: Revision
      type: object
      required:
      - key
      title: HostedConnector
    TargetRunBody:
      properties:
        schema_version:
          type: string
          title: Schema Version
        run_id:
          type: string
          title: Run Id
        target_id:
          type: string
          title: Target Id
        status:
          type: string
          title: Status
        coverage:
          anyOf:
          - type: string
          - type: 'null'
          title: Coverage
        jobs_sent:
          type: integer
          title: Jobs Sent
          default: 0
        observed:
          anyOf:
          - type: integer
          - type: 'null'
          title: Observed
        accepted:
          anyOf:
          - type: integer
          - type: 'null'
          title: Accepted
        rejected:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rejected
        batches:
          anyOf:
          - type: integer
          - type: 'null'
          title: Batches
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        http_status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Http Status
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
      type: object
      required:
      - schema_version
      - run_id
      - target_id
      - status
      title: TargetRunBody
    ConnectorIdent:
      properties:
        key:
          type: string
          title: Key
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        runtime_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Runtime Version
        revision:
          anyOf:
          - type: string
          - type: 'null'
          title: Revision
      type: object
      required:
      - key
      title: ConnectorIdent
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    HostedBatch:
      properties:
        schema_version:
          type: string
          title: Schema Version
        batch_id:
          type: string
          title: Batch Id
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
        target_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Id
        connector:
          anyOf:
          - $ref: '#/components/schemas/HostedConnector'
          - type: 'null'
        jobs:
          items:
            $ref: '#/components/schemas/DiscoveredJob'
          type: array
          title: Jobs
      type: object
      required:
      - schema_version
      - batch_id
      - jobs
      title: HostedBatch
      description: 'A first-party batch. `batch_id` makes the whole request replay-safe.


        One model for both versions rather than two: v2 adds two optional fields and forbids nothing, so

        a second class would exist only to restate the first. The route requires `run_id`/`target_id`

        when the schema_version says v2 — presence is a rule about the version, not about the shape.'
    ClassificationClaimBody:
      properties:
        limit:
          type: integer
          title: Limit
          default: 40
      type: object
      title: ClassificationClaimBody
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    EnrichmentCompleteBody:
      properties:
        results:
          items:
            $ref: '#/components/schemas/EnrichmentResultBody'
          type: array
          title: Results
      type: object
      required:
      - results
      title: EnrichmentCompleteBody
    EnrichmentResultBody:
      properties:
        task_id:
          type: string
          title: Task Id
        lease_token:
          type: string
          title: Lease Token
        url:
          type: string
          title: Url
        status:
          type: string
          title: Status
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        resolver:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolver
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        retry_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Retry At
      type: object
      required:
      - task_id
      - lease_token
      - url
      - status
      title: EnrichmentResultBody
    DiscoveredJob:
      properties:
        source:
          type: string
          title: Source
        title:
          type: string
          title: Title
        company:
          type: string
          title: Company
        external_id:
          anyOf:
          - type: string
          - type: 'null'
          title: External Id
        source_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Scope
        location:
          anyOf:
          - type: string
          - type: 'null'
          title: Location
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        apply_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Apply Url
        posted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Posted At
        job_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Type
        is_remote:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Remote
        salary_min:
          anyOf:
          - type: number
          - type: 'null'
          title: Salary Min
        salary_max:
          anyOf:
          - type: number
          - type: 'null'
          title: Salary Max
        salary_currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Salary Currency
        salary_interval:
          anyOf:
          - type: string
          - type: 'null'
          title: Salary Interval
        source_labels:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Source Labels
      type: object
      required:
      - source
      - title
      - company
      title: DiscoveredJob
    ClassificationCompleteBody:
      properties:
        results:
          items:
            $ref: '#/components/schemas/ClassificationResultBody'
          type: array
          maxItems: 40
          title: Results
      type: object
      required:
      - results
      title: ClassificationCompleteBody
    PollBody:
      properties:
        schema_version:
          type: string
          title: Schema Version
        connector:
          $ref: '#/components/schemas/ConnectorIdent'
        last_cycle:
          anyOf:
          - $ref: '#/components/schemas/LastCycle'
          - type: 'null'
      type: object
      required:
      - schema_version
      - connector
      title: PollBody