> ## Documentation Index
> Fetch the complete documentation index at: https://dev.jolts.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get company

> Metered known-company lookup using the same operation as GET /api/companies and MCP get_companies. Requires Idempotency-Key; identical retries share settlement across interfaces. Returns at most three current observations and supported domains, not a complete profile. Does not acquire data or call AI. Unknown companies return 404 after settling one request and zero deliveries.

Examples use fictional test data and illustrative IDs, dates, and allowances. They are not live prospects or current account balances.



## OpenAPI

````yaml /openapi.json get /api/companies/{id}
openapi: 3.1.0
info:
  title: Jolts API
  version: 1.0.0
  description: >-
    Implemented HTTP contract. Authentication uses an account-scoped bearer
    credential. Current coverage is partial; a matching company is not a
    guarantee of buying intent.


    Response examples use fictional test companies and illustrative IDs, dates
    and allowances. They are not live customer results or evidence of market
    coverage.
servers:
  - url: https://app.jolts.xyz
    description: Application API
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Find prospects and investigate their supporting evidence.
  - name: Observations
    description: Search individual company activities and inspect their sources.
  - name: Operations
    description: Start background work and retrieve its results.
  - name: Account
    description: Check your subscription and shared usage allowance.
paths:
  /api/companies/{id}:
    get:
      tags:
        - Companies
      summary: Get company
      description: >-
        Metered known-company lookup using the same operation as GET
        /api/companies and MCP get_companies. Requires Idempotency-Key;
        identical retries share settlement across interfaces. Returns at most
        three current observations and supported domains, not a complete
        profile. Does not acquire data or call AI. Unknown companies return 404
        after settling one request and zero deliveries.


        Examples use fictional test data and illustrative IDs, dates, and
        allowances. They are not live prospects or current account balances.
      operationId: getCompany
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
        - name: id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: Current supported company details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyDetail'
              examples:
                result:
                  $ref: '#/components/examples/getCompany200'
        '202':
          description: The same operation is already processing; poll its usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pending'
              examples:
                pending:
                  $ref: '#/components/examples/searchCompanies202'
        '401':
          description: Missing or revoked API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/invalidCredential'
        '402':
          description: An active or trialing subscription is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/subscriptionRequired'
        '404':
          description: Unknown company or no currently deliverable evidence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/getCompany404'
        '422':
          description: Invalid identifier, missing request key, or conflicting retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/invalidSearch'
        '429':
          description: Subscription request or delivery capacity reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/requestLimit'
components:
  schemas:
    CompanyDetail:
      type: object
      properties:
        company:
          type: object
          properties:
            id:
              type: integer
              minimum: 1
            name:
              type: string
            domains:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: integer
                    minimum: 1
                  hostname:
                    type: string
                required:
                  - id
                  - hostname
                additionalProperties: false
            observations:
              type: array
              items:
                $ref: '#/components/schemas/SupportingObservation'
              maxItems: 3
            limitations:
              type: array
              items:
                type: string
          required:
            - id
            - name
            - domains
            - observations
            - limitations
          additionalProperties: false
      required:
        - company
      additionalProperties: false
    Pending:
      type: object
      examples:
        - usage:
            id: 789
            status: pending
            request_key: first-company-search
            request_units: 0
            delivered_units: 0
            fresh_evidence_units: 0
          request_allowance:
            window_seconds: 18000
            window_remaining: 99
            weekly_remaining: 499
      properties:
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - usage
        - request_allowance
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retry_at:
              type: string
              format: date-time
              description: >-
                Advisory retry time for the reached capacity limit, based on
                usage at rejection. Other requests or completing reservations
                may change availability.
            retry_after_seconds:
              type: integer
              minimum: 0
              description: >-
                Seconds from rejection to retry_at. For stored failed
                operations, prefer the absolute retry_at timestamp.
          required:
            - code
            - message
          additionalProperties: false
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - error
      additionalProperties: false
    SupportingObservation:
      type: object
      description: >-
        One activity and its supporting sources. The example is fictional, not a
        live company result.
      examples:
        - id: 456
          kind: facility_expansion
          observed_fact: Example Logistics announced a new distribution warehouse.
          why_it_may_matter: >-
            A new warehouse may need handling equipment; no purchasing decision
            is confirmed.
          demand_class: proxy
          country: CA
          confidence: 0.8
          occurred_at: '2026-09-20T00:00:00Z'
          observed_at: '2026-09-21T12:00:00Z'
          expires_at: null
          evidence:
            - source_uri: https://logistics.example/news/warehouse
              excerpt: We are opening a new distribution warehouse.
              occurred_at: '2026-09-20T00:00:00Z'
              observed_at: '2026-09-21T12:00:00Z'
      properties:
        categories:
          $ref: '#/components/schemas/Categories'
        id:
          type: integer
          minimum: 1
        kind:
          type: string
          enum:
            - procurement_request
            - facility_expansion
            - company_profile
        observed_fact:
          type: string
        why_it_may_matter:
          type: string
        demand_class:
          type: string
          enum:
            - explicit_request
            - proxy
            - structural
        country:
          type: string
          enum:
            - CA
            - US
        confidence:
          type: number
          minimum: 0
          maximum: 1
        occurred_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Event time; may be null only for company_profile. Structural fit is
            not evidence of current buying intent.
        observed_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/Evidence'
      required:
        - id
        - kind
        - observed_fact
        - why_it_may_matter
        - demand_class
        - country
        - confidence
        - occurred_at
        - observed_at
        - expires_at
        - evidence
      additionalProperties: false
    Operation:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - pending
            - processing
            - delivered
            - failed
        request_key:
          type: string
        request_units:
          type: integer
          minimum: 0
        delivered_units:
          type: integer
          minimum: 0
        fresh_evidence_units:
          type: integer
          minimum: 0
      required:
        - id
        - status
        - request_key
        - request_units
        - delivered_units
        - fresh_evidence_units
      additionalProperties: false
    Allowance:
      type: object
      properties:
        window_seconds:
          type: integer
          minimum: 0
        window_remaining:
          type: integer
          minimum: 0
        weekly_remaining:
          type: integer
          minimum: 0
      required:
        - window_seconds
        - window_remaining
        - weekly_remaining
      additionalProperties: false
    Categories:
      type: array
      maxItems: 100
      description: >-
        Source-reported NAICS 2022 sector codes; industry classification, not
        products or buying intent.
      items:
        type: string
        enum:
          - '11'
          - '21'
          - '22'
          - '23'
          - 31-33
          - '42'
          - 44-45
          - 48-49
          - '51'
          - '52'
          - '53'
          - '54'
          - '55'
          - '56'
          - '61'
          - '62'
          - '71'
          - '72'
          - '81'
          - '92'
    Evidence:
      type: object
      properties:
        source_uri:
          type: string
          description: >-
            Source reference supplied with the evidence. For company profiles
            this may be a company homepage, not the origin of each profile field
            or an independently verified citation.
        excerpt:
          type: string
          description: >-
            Retained supporting text. For company profiles this is a
            provider-reported description, not necessarily a quotation from
            source_uri.
        occurred_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Source event time, or null for a structural company profile with no
            reported event date.
        last_seen_at:
          type: string
          format: date-time
          description: >-
            Latest retrieval of this unchanged source record; not a new event or
            independent verification.
        observed_at:
          type: string
          format: date-time
      required:
        - source_uri
        - excerpt
        - occurred_at
        - observed_at
      additionalProperties: false
  examples:
    getCompany200:
      summary: Illustrative result (fictional test data)
      value:
        company:
          id: 23
          name: Sequoia Freight
          domains:
            - id: 23
              hostname: sequoia.example.test
          observations:
            - id: 23
              kind: procurement_request
              observed_fact: Issued a request for fleet charging equipment at a new depot.
              why_it_may_matter: >-
                This observed company activity may be relevant to the search
                objective; verify fit against the evidence.
              demand_class: explicit_request
              country: US
              confidence: 1
              occurred_at: '2026-09-18T00:00:00Z'
              observed_at: '2026-09-25T02:47:06Z'
              expires_at: null
              evidence:
                - source_uri: https://sequoia.example.test/tenders/fleet-charging
                  excerpt: >-
                    Issued a request for fleet charging equipment at a new
                    depot.
                  occurred_at: '2026-09-18T00:00:00Z'
                  observed_at: '2026-09-25T02:47:06Z'
          limitations:
            - limited_source_coverage
    searchCompanies202:
      summary: Accepted; poll usage.id
      value:
        usage:
          id: 981239949
          status: pending
          request_key: company
          request_units: 0
          delivered_units: 0
          fresh_evidence_units: 0
        request_allowance:
          window_seconds: 10800
          window_remaining: 198
          weekly_remaining: 998
    invalidCredential:
      summary: invalid_api_key
      value:
        error:
          code: invalid_api_key
          message: Provide a valid API credential.
    subscriptionRequired:
      summary: subscription_required
      value:
        error:
          code: subscription_required
          message: An active or trialing subscription is required.
    getCompany404:
      summary: Record unavailable
      value:
        error:
          code: company_not_found
          message: No deliverable company has that ID.
    invalidSearch:
      summary: invalid_search
      value:
        error:
          code: invalid_search
          message: background must be a boolean
    requestLimit:
      summary: Request allowance reached (illustrative retry time)
      value:
        error:
          code: request_limit_reached
          message: The subscription request limit has been reached.
          retry_at: '2026-09-25T05:00:00Z'
          retry_after_seconds: 60
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````