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

# Create Custom Links

> Create one to 500 personalized links as one asynchronous job.

Requires `custom_links:write` and an `Idempotency-Key` header.

The response is `202 Accepted` with a durable job, a `Location` header for
polling, and `Retry-After: 2`. Valid links can be accepted even when other items
fail validation. Read the job items for deterministic per-input outcomes.


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/custom-links
openapi: 3.1.0
info:
  title: Hobbes API
  description: >

    Use the Hobbes API to read your organization's analyzed demo sessions,

    prospects, accounts, transcripts, and funnel metrics, and to create and
    manage

    personalized Custom Links.


    **Authentication**: create an API key in Settings → API Keys, then send it

    as `Authorization: Bearer <key>` (or `x-api-key: <key>`). Keys are

    org-scoped; responses only ever contain your organization's data.


    **Scopes**: keys carry scopes (`sessions:read`, `people:read`,

    `accounts:read`, `analytics:read`, `transcripts:read`, `custom_links:read`,

    `custom_links:write`). `custom_links:write` also satisfies read access. Raw

    transcript access is a separate opt-in scope with a daily quota. Existing
    API

    keys do not receive Custom Link scopes automatically.


    **Rate limits**: keys allow 120 requests per minute by default. Responses

    include `X-RateLimit-Limit` and `X-RateLimit-Remaining`; 429 responses
    include

    `Retry-After`. Transcript access has a separate quota of 2,000 reads per

    organization per UTC day. Custom Link mutations are limited to 10 requests
    per

    minute per organization. Creation and thumbnail rendering also use weighted

    hourly and daily organization quotas, so one request containing 500 links is

    one HTTP request but consumes up to 500 creation and 500 render units.


    **Support**: every response carries an `X-Request-ID` header. Include it
    when

    reporting an issue so we can find the exact request in our logs.


    **Stability**: changes within v1 are additive only. Fields may be added to

    responses; existing fields are never removed or renamed.
  version: 1.0.0
servers:
  - url: https://api-us.hihobbes.com
    description: Production
security:
  - bearer: []
  - apiKeyHeader: []
tags:
  - name: Sessions
    description: Analyzed demo sessions and their transcripts.
  - name: People
    description: Prospect profiles aggregated across sessions.
  - name: Accounts
    description: Company-level engagement rollups by email domain.
  - name: Metrics
    description: Aggregate funnel performance over a trailing window.
  - name: Custom Links
    description: Create and manage personalized links.
  - name: Custom Link Jobs
    description: Poll, cancel, and retry asynchronous Custom Link work.
  - name: Custom Link Campaigns
    description: Organize Custom Links into campaigns.
paths:
  /api/v1/custom-links:
    post:
      tags:
        - Custom Links
      summary: Create Custom Links
      description: >-
        Validate and accept 1-500 Custom Links as one asynchronous job. Requires
        an `Idempotency-Key` header.
      operationId: v1_create_custom_links
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 255
            title: Idempotency-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomLinksCreateRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomLinkJobResponse'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Location:
              description: URL of the accepted Custom Link job.
              schema:
                type: string
            Retry-After:
              description: Suggested seconds before the first status poll.
              schema:
                type: integer
                example: 2
        '401':
          description: API key required or invalid.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key required or invalid.
        '403':
          description: API key does not include the required scope.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key does not include the required scope.
        '409':
          description: The operation conflicts with current state or idempotency history.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: >-
                      The operation conflicts with current state or idempotency
                      history.
        '422':
          description: A path, query, header, or request field failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
        '429':
          description: Rate limit or organization quota exceeded.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
            X-RateLimit-Reset:
              description: Unix timestamp when the limiting window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Rate limit or organization quota exceeded.
        '503':
          description: Thumbnail processing is temporarily unavailable.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
            X-RateLimit-Reset:
              description: Unix timestamp when the limiting window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Thumbnail processing is temporarily unavailable.
components:
  schemas:
    CustomLinksCreateRequest:
      properties:
        campaign:
          $ref: '#/components/schemas/CampaignReference'
        generateThumbnails:
          type: boolean
          title: Generatethumbnails
          default: true
        links:
          items:
            properties:
              externalId:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Externalid
              displayName:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Displayname
              firstName:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Firstname
              lastName:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Lastname
              email:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Email
              phone:
                anyOf:
                  - type: string
                    maxLength: 50
                  - type: 'null'
                title: Phone
              role:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Role
              company:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Company
              context:
                anyOf:
                  - type: string
                    maxLength: 10000
                  - type: 'null'
                title: Context
              shareTitle:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Sharetitle
              shareDescription:
                anyOf:
                  - type: string
                    maxLength: 500
                  - type: 'null'
                title: Sharedescription
              shareThumbnailUrl:
                anyOf:
                  - type: string
                    maxLength: 2083
                    minLength: 1
                    format: uri
                  - type: 'null'
                title: Sharethumbnailurl
              prospectLogoUrl:
                anyOf:
                  - type: string
                    maxLength: 2083
                    minLength: 1
                    format: uri
                  - type: 'null'
                title: Prospectlogourl
              prospectDomain:
                anyOf:
                  - type: string
                    maxLength: 255
                  - type: 'null'
                title: Prospectdomain
              active:
                type: boolean
                title: Active
                default: true
            additionalProperties: false
            type: object
            title: CustomLinkInput
          type: array
          maxItems: 500
          minItems: 1
          title: Links
      additionalProperties: false
      type: object
      required:
        - campaign
        - links
      title: CustomLinksCreateRequest
    CustomLinkJobResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        type:
          type: string
          enum:
            - create
            - thumbnail
            - retry
          title: Type
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - completed_with_errors
            - cancelled
            - failed
          title: Status
        campaignId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Campaignid
        parentJobId:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Parentjobid
        totalItems:
          type: integer
          title: Totalitems
        createdCount:
          type: integer
          title: Createdcount
          default: 0
        failedCount:
          type: integer
          title: Failedcount
          default: 0
        thumbnailQueuedCount:
          type: integer
          title: Thumbnailqueuedcount
          default: 0
        thumbnailProcessingCount:
          type: integer
          title: Thumbnailprocessingcount
          default: 0
        thumbnailGeneratedCount:
          type: integer
          title: Thumbnailgeneratedcount
          default: 0
        thumbnailProvidedCount:
          type: integer
          title: Thumbnailprovidedcount
          default: 0
        thumbnailFallbackCount:
          type: integer
          title: Thumbnailfallbackcount
          default: 0
        thumbnailFailedCount:
          type: integer
          title: Thumbnailfailedcount
          default: 0
        progress:
          type: number
          maximum: 100
          minimum: 0
          title: Progress
          default: 0
        pollAfterSeconds:
          type: integer
          maximum: 60
          minimum: 1
          title: Pollafterseconds
          default: 2
        cancelRequested:
          type: boolean
          title: Cancelrequested
          default: false
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        startedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Startedat
        completedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completedat
      type: object
      required:
        - id
        - type
        - status
        - totalItems
        - createdAt
        - updatedAt
      title: CustomLinkJobResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CampaignReference:
      properties:
        id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Id
        name:
          anyOf:
            - type: string
              maxLength: 255
              minLength: 1
            - type: 'null'
          title: Name
      additionalProperties: false
      type: object
      title: CampaignReference
    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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Hobbes API key with the `hb_live_` prefix.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative to the Bearer authorization header.

````