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

# Read this reference

> Body: none.

Returns this document, the OpenAPI 3.1 reference of `/v1`.

See also [Billing](/api/billing), [Rate limits](/api/rate-limits).



## OpenAPI

````yaml GET /v1/openapi.json
openapi: 3.1.0
info:
  title: Orbb API
  version: v1
  description: >-
    Who knows whom, and how well: the people connected to a person, the
    connection between two people, and the person behind an email or a name.
    Every call is a `POST` with a JSON body, except `GET /v1/openapi.json`.


    Read [Authentication](/api/authentication), [Errors](/api/errors),
    [Jobs](/api/jobs), [Billing](/api/billing) and [Rate
    limits](/api/rate-limits) before your first integration.
servers:
  - url: https://api.orbb.com
    description: Production
security:
  - bearer: []
paths:
  /v1/openapi.json:
    get:
      summary: Read this reference
      description: |-
        Body: none.

        Returns this document, the OpenAPI 3.1 reference of `/v1`.

        See also [Billing](/api/billing), [Rate limits](/api/rate-limits).
      operationId: openapi
      responses:
        '200':
          description: This document.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                type: object
        '400':
          description: >-
            Bad Request.


            - `invalid_body`: The body could not be parsed (not valid JSON,
            larger than 16 kB, or not received in full), or does not match the
            operation’s body. See [Errors](/api/errors). Fix the body. `detail`
            names the field when there is one.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized.


            - `invalid_session`: A token in the form of a session token (three
            parts separated by dots) was refused: expired, or not a session of
            the console. Sign in to the console again, or use an API key.


            - `invalid_api_key`: The `Authorization` header is missing or is not
            `Bearer <token>`, or the key is unknown, revoked or expired. The
            answer is the same whatever the reason. Check the key, or create a
            new one in the console.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too Many Requests.


            - `rate_limited`: The account made more calls in the last minute
            than `RateLimit-Limit` allows. Wait `Retry-After` seconds, then
            repeat the same request.


            - `too_many_concurrent`: The account has too many calls waiting for
            an answer at once. Wait for a call to be answered, or `Retry-After`
            seconds, then repeat the same request.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Service Unavailable.


            - `unavailable`: The API could not complete the call, or could not
            check the token or the rate limits. Repeat the same request, backing
            off.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    X-Request-Id:
      description: >-
        The id of the request. Every answer carries it; an error body repeats it
        as `request_id`. See Request ids.
      schema:
        type: string
    RateLimit-Limit:
      description: >-
        The calls the account may make per minute. On every answer past
        authentication: not on a `401`, nor on a `400 invalid_body` for a body
        that could not be parsed. See Rate limits.
      schema:
        type: integer
    Retry-After:
      description: The seconds to wait before calling again. On every `429`.
      schema:
        type: integer
  schemas:
    Error:
      type: object
      properties:
        error:
          description: 'The error code. Stable: branch on it.'
          type: string
          enum:
            - invalid_body
            - invalid_session
            - invalid_api_key
            - invalid_limit
            - invalid_types
            - invalid_min_strength
            - invalid_cursor
            - same_person
            - person_not_found
            - ambiguous_person
            - result_unavailable
            - not_found
            - too_many_keys
            - unavailable
            - rate_limited
            - too_many_concurrent
            - research_busy
            - insufficient_balance
            - invalid_max_tokens
            - billing_account_missing
        detail:
          description: >-
            A sentence that explains the error, for a person to read. Its
            wording can change: do not parse it.
          type: string
        request_id:
          description: The id of the request, the same as the `X-Request-Id` header.
          type: string
        candidates:
          description: 'With `422 ambiguous_person` only: every person the id matched.'
          type: array
          items:
            type: object
            properties:
              key:
                description: >-
                  The person’s key: the public identifier percent-decoded and
                  lower-cased. Two people in the answers are the same person
                  when their keys are equal.
                type: string
              publicId:
                description: >-
                  The person’s current LinkedIn public identifier, the part
                  after `/in/` of the profile URL. It is a valid `id`, `a`, `b`
                  or `target` in any call. For a person with no known profile,
                  the identifier as the call gave it, in the form of `key`.
                type: string
              full_name:
                description: The person’s name. Absent when no known profile carries one.
                type: string
              role:
                description: >-
                  The title of the person’s current position; without one, the
                  profile’s headline. Absent when the profile has neither, or no
                  profile is known.
                type: string
              company:
                description: >-
                  The name of the company of the current position shown. Absent
                  when unknown.
                type: string
              companyPublicId:
                description: >-
                  The LinkedIn page of that company, as `company/<slug>`, or
                  `showcase/<slug>` for a showcase page. Absent when unknown.
                type: string
            required:
              - key
              - publicId
      required:
        - error
        - detail
        - request_id
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        An API key, `orbb_sk_…`, created in the console; or the console’s
        session token. See Authentication.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.