openapi: 3.1.0
info:
  title: Blinq Public API
  version: 1.0.0
  description: |-
    The Blinq API provides programmatic access to your contacts and notes. Connect Blinq to your existing tools, keep contact records in sync, and build workflows on note summaries and transcripts.

    API access requires a [Blinq Pro or Business plan](https://blinq.me/pricing) and a verified email address. Keys are personal and scoped: they never grant access beyond what their owner can already see.

    ## Access scopes

    Choose one or more scopes when creating a key.

    | Scope | Grants access to |
    | --- | --- |
    | `blinq:contacts:read` | Your personal contacts. Business owners and admins can list contacts; members can retrieve a visible contact by a known ID. |
    | `blinq:cards:read` | Lightweight card summaries and sharing links in your personal workspace and business workspaces you own or administer. |
    | `blinq:notes:read` | Your own notes and transcripts. |
    | `blinq:identity:read` | Your identity and the workspaces you belong to. |

    ## Creating and revoking keys

    1. In the Blinq web app, open Settings > API keys.
    2. Select **Create new key**, choose a name and the scopes your integration needs, then select **Generate API key**.
    3. Copy the key when it is shown. The secret is displayed only once; store it securely.

    To revoke a key, return to Settings > API keys and select **Revoke**. A revoked key stops authenticating new requests immediately.

    ## Quick start

    Send your key to `https://api.blinq.me` as `Authorization: Bearer <api-key>`. In the documentation playground, enter only the key, without `Bearer`.

    List your notes (requires `blinq:notes:read`):

    ```bash
    curl 'https://api.blinq.me/v1/notes?limit=5' \
      -H 'Authorization: Bearer <api-key>'
    ```

    Contact routes are scoped to one workspace. `GET /v1/workspaces` (requires `blinq:identity:read`) discovers workspace IDs; listing contacts from a known workspace ID needs only `blinq:contacts:read`:

    ```bash
    curl 'https://api.blinq.me/v1/workspaces/<workspace-id>/contacts?limit=5' \
      -H 'Authorization: Bearer <api-key>'
    ```

    ## Errors

    All errors return a JSON body with `status` (the HTTP status code), `error` (the HTTP status name, such as `Bad Request`), `code` (a machine-readable error code), `message` (a human-readable description; wording may change, so branch on `code` instead), and `request_id` (the unique ID of the request, also returned as the `X-Request-Id` header). Validation errors may add a `details` array naming each parameter or body field that failed.

    Any route can return `400` when query parameters or the body are invalid (unknown query parameters are rejected), `401` when the API key is missing or invalid, `403` when the key is missing a required scope, its owner lacks permission, or the account plan does not include the operation, and `429` when the rate limit is reached (see Rate limits). Any route can also return `500` when an unexpected error occurs (quote `request_id` when contacting support) and `503` when API key verification or the requested operation is unavailable.

    The responses documented on each route below list only the status codes specific to that operation.

    ## Rate limits

    Each person can make up to **25 requests in any 5-second window**, or **300 requests per minute** at a steady rate. The quota is shared across all of their API keys; creating more keys does not increase it. When the limit is reached, the API returns `429 Too Many Requests` with a `Retry-After` header in seconds. Wait that long before retrying.
components:
  securitySchemes:
    API key:
      type: http
      scheme: bearer
      description: |-
        Send a Blinq API key as `Authorization: Bearer <api-key>`; enter only the key in the documentation playground.

        Create and revoke keys in the Blinq web app under Settings > API keys.

        The key needs the scopes required by the operation, and public API access requires a Pro or Business plan.
  schemas: {}
paths:
  /v1/notes:
    get:
      operationId: listNotes
      summary: List notes
      tags:
      - Notes
      description: |-
        Returns a paginated list of the authenticated user's note metadata.

        Notes are sorted by creation time, newest first, unless `order_by` specifies update time. Ties are broken by note ID, so pages are deterministic.

        For an initial sync, page with `order_by=updated_at` until `has_more` is `false`. For incremental syncs, record a checkpoint before each run, pass it as `updated_at_gte` (inclusive) with a small overlap, upsert by `id`, and advance the checkpoint only after every page succeeds.

        Deleted notes are omitted. There is no deletion feed; periodically reconcile a complete list of IDs to detect removals. Timestamp filtering alone does not provide lossless synchronization.

        Get an individual note to read its content.

        Requires the `blinq:notes:read` scope.
      parameters:
      - schema:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        in: query
        name: created_after
        required: false
        description: Return notes created after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (exclusive).
      - schema:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        in: query
        name: created_before
        required: false
        description: Return notes created before this ISO 8601 timestamp with a timezone, such as `2026-11-01T00:00:00Z` (exclusive).
      - schema:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        in: query
        name: updated_at_gte
        required: false
        description: Return notes last updated at or after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (inclusive). Deleted notes are excluded.
      - schema:
          default: created_at
          type: string
          enum:
          - created_at
          - updated_at
        in: query
        name: order_by
        required: false
        description: The timestamp used to sort notes in descending order. Keep this value unchanged between pages.
      - schema:
          type: string
          minLength: 1
        in: query
        name: cursor
        required: false
        description: The `next_cursor` from the previous response. Omit on the first request. Keep filters and `order_by` unchanged between pages.
      - schema:
          default: 25
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        in: query
        name: limit
        required: false
        description: The maximum number of notes to return per page.
      security:
      - API key: []
      responses:
        '200':
          description: One page of note metadata.
          content:
            application/json:
              schema:
                type: object
                properties:
                  notes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the note.
                        title:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The custom title set by the user, otherwise the generated title, or `null` when the note has neither.
                        created_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the user's device created the note, as an ISO 8601 timestamp.
                        updated_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the note was last updated, as an ISO 8601 timestamp.
                        deleted_at:
                          type: 'null'
                          description: Always `null`. Deleted notes are not returned.
                        status:
                          type: string
                          enum:
                          - processing
                          - ready
                          - failed
                          - blocked
                          description: |-
                            The processing state of the note.

                            `processing`: recording or processing is in progress.

                            `ready`: no recording or processing is pending. Content may be empty or null.

                            `failed`: processing failed. Partial content may be available.

                            `blocked`: processing is blocked by the account plan or usage limits.
                        type:
                          anyOf:
                          - type: string
                            enum:
                            - voice_note
                            - phone_call
                            - text
                          - type: 'null'
                          description: 'How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable.'
                        share_url:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings.
                        linked_contacts:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: The ID of the linked contact.
                              full_name:
                                anyOf:
                                - type: string
                                - type: 'null'
                                description: The display name of the linked contact, or `null` when none is available.
                              workspace_id:
                                type: string
                                description: The personal workspace ID to pass when getting this contact.
                            required:
                            - id
                            - full_name
                            - workspace_id
                            additionalProperties: false
                          description: The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access.
                      required:
                      - id
                      - title
                      - created_at
                      - updated_at
                      - deleted_at
                      - status
                      - type
                      - share_url
                      - linked_contacts
                      additionalProperties: false
                      description: Note metadata.
                      example:
                        id: note-id
                        title: Meeting notes
                        created_at: '2026-10-01T00:00:00.000Z'
                        updated_at: '2026-10-01T00:00:00.000Z'
                        deleted_at: null
                        status: ready
                        type: voice_note
                        share_url: https://note.blinq.me/share-id
                        linked_contacts:
                        - id: contact-id
                          full_name: Jane Doe
                          workspace_id: workspace-id
                    description: Note metadata for this page. Get an individual note to read its content.
                  has_more:
                    type: boolean
                    description: Whether another page of notes is available.
                  next_cursor:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`.
                  total_count:
                    anyOf:
                    - type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    - type: 'null'
                    description: The total number of notes matching the filters. Returned on the first page; `null` on subsequent pages.
                required:
                - notes
                - has_more
                - next_cursor
                - total_count
                additionalProperties: false
                description: One page of note metadata.
              examples:
                example1:
                  value:
                    notes:
                    - id: note-id
                      title: Meeting notes
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      deleted_at: null
                      status: ready
                      type: voice_note
                      share_url: https://note.blinq.me/share-id
                      linked_contacts:
                      - id: contact-id
                        full_name: Jane Doe
                        workspace_id: workspace-id
                    has_more: false
                    next_cursor: null
                    total_count: 1
                example2:
                  value:
                    notes:
                    - id: note-id
                      title: Meeting notes
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      deleted_at: null
                      status: ready
                      type: voice_note
                      share_url: https://note.blinq.me/share-id
                      linked_contacts:
                      - id: contact-id
                        full_name: Jane Doe
                        workspace_id: workspace-id
                    has_more: true
                    next_cursor: opaque-page-2
                    total_count: 3
                example3:
                  value:
                    notes:
                    - id: note-id-2
                      title: Meeting notes
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      deleted_at: null
                      status: ready
                      type: voice_note
                      share_url: https://note.blinq.me/share-id
                      linked_contacts:
                      - id: contact-id
                        full_name: Jane Doe
                        workspace_id: workspace-id
                    has_more: true
                    next_cursor: opaque-page-3
                    total_count: null
                example4:
                  value:
                    notes:
                    - id: note-id-3
                      title: null
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      deleted_at: null
                      status: ready
                      type: voice_note
                      share_url: null
                      linked_contacts:
                      - id: contact-id
                        full_name: Jane Doe
                        workspace_id: workspace-id
                    has_more: false
                    next_cursor: null
                    total_count: null
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
  /v1/notes/search:
    get:
      operationId: searchNotes
      summary: Search notes
      tags:
      - Notes
      description: |-
        Searches the authenticated user's indexed note titles and bodies, including recording summaries and saved text, using keyword and semantic matching.

        Returns up to `limit` results ordered from most to least relevant. Search does not support pagination. `is_truncated` indicates that additional results were found.

        New or updated notes may be missing until indexing completes. Changing `limit` can change the ranking. Use the list endpoint to retrieve all notes and the get endpoint to read note content.

        Requires the `blinq:notes:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        example: launch pricing
        in: query
        name: query
        required: true
        description: Search terms to match against indexed titles and bodies, including recording summaries and saved text.
      - schema:
          default: 10
          type: integer
          exclusiveMinimum: 0
          maximum: 25
        in: query
        name: limit
        required: false
        description: The maximum number of search results to return. Search does not support pagination.
      security:
      - API key: []
      responses:
        '200':
          description: Search results ordered by relevance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  notes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the note.
                        title:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The custom title set by the user, otherwise the generated title, or `null` when the note has neither.
                        created_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the user's device created the note, as an ISO 8601 timestamp.
                        updated_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the note was last updated, as an ISO 8601 timestamp.
                        deleted_at:
                          type: 'null'
                          description: Always `null`. Deleted notes are not returned.
                        status:
                          type: string
                          enum:
                          - processing
                          - ready
                          - failed
                          - blocked
                          description: |-
                            The processing state of the note.

                            `processing`: recording or processing is in progress.

                            `ready`: no recording or processing is pending. Content may be empty or null.

                            `failed`: processing failed. Partial content may be available.

                            `blocked`: processing is blocked by the account plan or usage limits.
                        type:
                          anyOf:
                          - type: string
                            enum:
                            - voice_note
                            - phone_call
                            - text
                          - type: 'null'
                          description: 'How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable.'
                        share_url:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings.
                        linked_contacts:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                                description: The ID of the linked contact.
                              full_name:
                                anyOf:
                                - type: string
                                - type: 'null'
                                description: The display name of the linked contact, or `null` when none is available.
                              workspace_id:
                                type: string
                                description: The personal workspace ID to pass when getting this contact.
                            required:
                            - id
                            - full_name
                            - workspace_id
                            additionalProperties: false
                          description: The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access.
                      required:
                      - id
                      - title
                      - created_at
                      - updated_at
                      - deleted_at
                      - status
                      - type
                      - share_url
                      - linked_contacts
                      additionalProperties: false
                      description: Note metadata.
                      example:
                        id: note-id
                        title: Meeting notes
                        created_at: '2026-10-01T00:00:00.000Z'
                        updated_at: '2026-10-01T00:00:00.000Z'
                        deleted_at: null
                        status: ready
                        type: voice_note
                        share_url: https://note.blinq.me/share-id
                        linked_contacts:
                        - id: contact-id
                          full_name: Jane Doe
                          workspace_id: workspace-id
                    description: Note metadata ordered from most to least relevant. Results may omit notes that have not been indexed.
                  is_truncated:
                    type: boolean
                    description: Whether this search found more results than `limit`. A value of `false` does not guarantee that every note was searched. Use the list endpoint to retrieve all notes.
                required:
                - notes
                - is_truncated
                additionalProperties: false
                description: Search results ordered by relevance.
              example:
                notes:
                - id: note-id
                  title: Pricing discussion
                  created_at: '2026-10-01T00:00:00.000Z'
                  updated_at: '2026-10-01T00:00:00.000Z'
                  deleted_at: null
                  status: ready
                  type: phone_call
                  share_url: null
                  linked_contacts: []
                is_truncated: false
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
  /v1/notes/query:
    post:
      operationId: queryNotes
      summary: Ask a question about notes
      tags:
      - Notes
      description: |-
        Generates an answer to a question using the authenticated user's note titles and note bodies (AI summaries for recordings, saved text for typed notes). Transcripts are not used, and each note body is truncated to 8,000 UTF-16 code units.

        Pass between 1 and 8 of your own `note_ids` to answer from specific notes, or omit the field to let the API select up to 10 of the most relevant notes automatically.

        The answer contains inline markers such as `[1]` or `[1, 2]`: one-based positions in `citations`, where each unique note is numbered in order of first appearance and repeat references reuse the same number.

        When no accessible notes match, the answer is `No accessible notes were available to answer this question.` If an answer cannot be generated, the request fails with `503` and the message `Blinq could not generate an answer. Try again later.`

        Requires the `blinq:notes:read` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                  description: A natural-language question. Answers draw on note titles and note bodies (the AI summary for a recording or the saved text of a typed note), not transcripts. Each note body is truncated to 8,000 UTF-16 code units.
                note_ids:
                  description: Restricts the answer to between 1 and 8 notes you own. Omit to let the API select up to 10 of the most relevant notes automatically. IDs of inaccessible notes are ignored.
                  minItems: 1
                  maxItems: 8
                  type: array
                  items:
                    type: string
                    minLength: 1
              required:
              - query
              additionalProperties: false
            examples:
              example1:
                value:
                  query: What did we decide about the launch?
              example2:
                value:
                  query: What follow-up actions did we agree on?
                  note_ids:
                  - note-id-1
                  - note-id-2
      security:
      - API key: []
      responses:
        '200':
          description: The generated answer and its cited notes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  answer:
                    type: string
                    description: The generated answer. Inline markers such as `[1]` or `[1, 2]` are one-based positions in `citations`. Each unique note is numbered in order of first appearance, and repeat references reuse the same number. When no accessible notes match, the answer is `No accessible notes were available to answer this question.`
                  citations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The cited note ID.
                        title:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The custom title of the cited note, otherwise its generated title, or `null` when it has neither.
                        share_url:
                          type: string
                          description: A URL to view the cited note in a browser. Access follows the existing sharing settings; querying notes does not change them.
                      required:
                      - id
                      - title
                      - share_url
                      additionalProperties: false
                    description: The unique source notes, in order of first appearance in the answer. Empty when the answer has no citations.
                required:
                - answer
                - citations
                additionalProperties: false
                description: The generated answer and its cited notes.
              example:
                answer: The launch moved to November [1] and the pricing page still needs sign-off [1, 2]. Reply to Dana once legal approves. [2]
                citations:
                - id: note-id-1
                  title: Launch planning
                  share_url: https://note.blinq.me/share-id-1
                - id: note-id-2
                  title: Call with Dana
                  share_url: https://note.blinq.me/share-id-2
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '413':
          description: Payload too large - The request body exceeds the maximum allowed size
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Payload too large - The request body exceeds the maximum allowed size
              example:
                status: 413
                error: Payload Too Large
                code: invalid_request
                message: Request body is too large
                request_id: req-1
        '415':
          description: Unsupported media type - The request body must be `application/json`
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unsupported media type - The request body must be `application/json`
              example:
                status: 415
                error: Unsupported Media Type
                code: unsupported_media_type
                message: 'Unsupported Media Type: text/plain'
                request_id: req-1
  /v1/notes/{id}:
    get:
      operationId: getNote
      summary: Get note
      tags:
      - Notes
      description: |-
        Gets a note owned by the authenticated user, including its content or AI summary when available.

        Missing notes and notes owned by another user both return `404`.

        Requires the `blinq:notes:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: id
        required: true
        description: The note ID.
      security:
      - API key: []
      responses:
        '200':
          description: The requested note.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the note.
                  title:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The custom title set by the user, otherwise the generated title, or `null` when the note has neither.
                  created_at:
                    type: string
                    format: date-time
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    description: When the user's device created the note, as an ISO 8601 timestamp.
                  updated_at:
                    type: string
                    format: date-time
                    pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    description: When the note was last updated, as an ISO 8601 timestamp.
                  deleted_at:
                    type: 'null'
                    description: Always `null`. Deleted notes are not returned.
                  status:
                    type: string
                    enum:
                    - processing
                    - ready
                    - failed
                    - blocked
                    description: |-
                      The processing state of the note.

                      `processing`: recording or processing is in progress.

                      `ready`: no recording or processing is pending. Content may be empty or null.

                      `failed`: processing failed. Partial content may be available.

                      `blocked`: processing is blocked by the account plan or usage limits.
                  type:
                    anyOf:
                    - type: string
                      enum:
                      - voice_note
                      - phone_call
                      - text
                    - type: 'null'
                    description: 'How the note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note. `null` when the type is unavailable.'
                  share_url:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: A URL for viewing the note in a browser, or `null` when the note has no share link. Reading a note never creates a share link or changes sharing settings.
                  linked_contacts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the linked contact.
                        full_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The display name of the linked contact, or `null` when none is available.
                        workspace_id:
                          type: string
                          description: The personal workspace ID to pass when getting this contact.
                      required:
                      - id
                      - full_name
                      - workspace_id
                      additionalProperties: false
                    description: The contacts linked to the note, or an empty array when there are none. Retrieving a linked contact requires `blinq:contacts:read` and contact access.
                  content:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: 'The stored body: an AI summary for a recording or saved text for a text note. `null` means no body is stored; an empty stored body remains `""`. Use `status` to determine processing state.'
                  content_format:
                    type: 'null'
                    description: 'Always `null`: the backend does not record the content format. Treat the stored body as plain text unless your integration explicitly supports its markup.'
                  source:
                    anyOf:
                    - type: string
                      enum:
                      - mobile
                      - watch
                      - device
                    - type: 'null'
                    description: 'The device type that recorded the note: a `mobile` phone, a `watch`, or the Blinq notetaker `device`. `null` when unknown.'
                required:
                - id
                - title
                - created_at
                - updated_at
                - deleted_at
                - status
                - type
                - share_url
                - linked_contacts
                - content
                - content_format
                - source
                additionalProperties: false
                description: The requested note.
              example:
                id: note-id
                title: Meeting notes
                created_at: '2026-10-01T00:00:00.000Z'
                updated_at: '2026-10-01T00:00:00.000Z'
                deleted_at: null
                status: ready
                type: voice_note
                share_url: https://note.blinq.me/share-id
                linked_contacts:
                - id: contact-id
                  full_name: Jane Doe
                  workspace_id: workspace-id
                content: |-
                  ## Next steps

                  - Share the project proposal.
                content_format: null
                source: mobile
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '404':
          description: Not found - The note does not exist or belongs to another user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Not found - The note does not exist or belongs to another user
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
  /v1/notes/{id}/transcript:
    get:
      operationId: getNoteTranscript
      summary: Get note transcript
      tags:
      - Notes
      description: |-
        Gets the complete plain-text transcript of a voice note or phone call owned by the authenticated user.

        Returns `text: null` when no transcript is stored. An empty stored transcript is returned as `text: ""` with `status: "available"`. Check `status` and `retry_after` before polling.

        Transcripts are returned in full, without pagination.

        Missing notes and notes owned by another user both return `404`.

        Requires the `blinq:notes:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: id
        required: true
        description: The note ID.
      security:
      - API key: []
      responses:
        '200':
          description: The requested note transcript.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - available
                    - processing
                    - recording
                    - blocked
                    - failed
                    - unavailable
                    - not_applicable
                    description: 'available: text is ready; processing: retry later; recording: capture is ongoing; blocked: action is required in Blinq; failed: processing failed; unavailable: no transcript exists; not_applicable: a typed note.'
                  retry_after:
                    anyOf:
                    - type: integer
                      exclusiveMinimum: 0
                      maximum: 9007199254740991
                    - type: 'null'
                    description: Suggested polling delay in seconds while processing; null for other states.
                  text:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The complete plain-text transcript, or `null` when none is stored. An empty stored transcript is returned as `""` with status `available`.
                required:
                - status
                - retry_after
                - text
                additionalProperties: false
                description: The requested note transcript.
              examples:
                example1:
                  value:
                    status: available
                    retry_after: null
                    text: Let's send the proposal tomorrow.
                example2:
                  value:
                    status: available
                    retry_after: null
                    text: ''
                example3:
                  value:
                    status: processing
                    retry_after: 5
                    text: null
                example4:
                  value:
                    status: not_applicable
                    retry_after: null
                    text: null
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '404':
          description: Not found - The note does not exist or belongs to another user
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Not found - The note does not exist or belongs to another user
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
  /v1/me:
    get:
      operationId: getMe
      summary: Get the authenticated user
      tags:
      - Me
      description: |-
        Returns the user the supplied API key acts as: their `user_id` and their sign-in `email`, which is `null` when the user has none.

        Use it to confirm whose account an integration is accessing before listing workspaces or fetching data. The user is derived from the API key; the endpoint accepts no parameters.

        Requires the `blinq:identity:read` scope.
      security:
      - API key: []
      responses:
        '200':
          description: The authenticated user the API key acts as.
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    description: The ID of the user the API key acts as.
                  email:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The user's sign-in email address, or null when the user has none.
                required:
                - user_id
                - email
                additionalProperties: false
                description: The authenticated user the API key acts as.
              example:
                user_id: user_123
                email: person@example.com
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
  /v1/workspaces:
    get:
      operationId: listWorkspaces
      summary: List workspaces
      tags:
      - Workspaces
      description: |-
        Returns every workspace the authenticated user belongs to, including member workspaces, in one response without pagination, filters, or a specified order. An empty array means the user belongs to no workspaces.

        Use a workspace's `id` to list or retrieve contacts. The `role` is the API key owner's role in that workspace. Membership alone does not grant contact-list access; the contact endpoints enforce their own permissions, and workspace discovery is only needed when the workspace ID is not already known.

        Requires the `blinq:identity:read` scope.
      security:
      - API key: []
      responses:
        '200':
          description: The authenticated user's workspaces.
          content:
            application/json:
              schema:
                type: object
                properties:
                  workspaces:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The workspace ID to use when filtering or retrieving contacts.
                        name:
                          type: string
                          description: The workspace name.
                        type:
                          type: string
                          enum:
                          - personal
                          - business
                          description: Whether this is a personal workspace (`personal`) or a business workspace (`business`).
                        role:
                          type: string
                          enum:
                          - owner
                          - admin
                          - member
                          description: 'The API key owner''s role in the workspace: `owner`, `admin`, or `member`. Listing business workspace contacts requires `owner` or `admin`; retrieving a visible contact by known ID also allows `member`.'
                      required:
                      - id
                      - name
                      - type
                      - role
                      additionalProperties: false
                    description: Every workspace the authenticated user belongs to, without pagination and in no specified order. An empty array means the user belongs to none.
                required:
                - workspaces
                additionalProperties: false
                description: The authenticated user's workspaces.
              example:
                workspaces:
                - id: workspace-id
                  name: Acme
                  type: business
                  role: admin
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
  /v1/workspaces/{workspace_id}/contacts:
    get:
      operationId: listContacts
      summary: List contacts
      tags:
      - Contacts
      description: |-
        Returns a paginated list of contact summaries from your personal workspace or a business workspace you own or administer. Business members receive an empty list. The workspace path segment only narrows which accessible contacts are returned; it never grants additional access.

        Deleted contacts, hidden contacts, and company-directory entries are excluded.

        Contacts are sorted by creation time, newest first, with the contact ID as a tie-breaker, so pages are deterministic.

        Use a contact's `id` to retrieve its full details from the same workspace.

        Requires the `blinq:contacts:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: query
        name: cursor
        required: false
        description: The `next_cursor` returned by the previous response. Omit for the first page. Keep filters unchanged between pages.
      - schema:
          type: string
          minLength: 1
        in: query
        name: search
        required: false
        description: Filters contacts using a case-insensitive substring match against card names, job titles, company names, and saved text notes.
      - schema:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        in: query
        name: updated_at_gte
        required: false
        description: Return contact records last updated at or after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (inclusive). Deleted contacts are excluded. Changes to linked resources do not necessarily update the contact record.
      - schema:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        in: query
        name: created_at_gte
        required: false
        description: Include contacts created at or after this ISO 8601 timestamp with a timezone, such as `2026-10-01T00:00:00Z` (inclusive).
      - schema:
          type: string
          format: date-time
          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
        in: query
        name: created_at_lte
        required: false
        description: Include contacts created at or before this ISO 8601 timestamp with a timezone, such as `2026-10-31T23:59:59Z` (inclusive).
      - schema:
          default: 25
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        in: query
        name: limit
        required: false
        description: The maximum number of contacts to return per page.
      - schema:
          type: string
          minLength: 1
        in: path
        name: workspace_id
        required: true
        description: The workspace ID. Use an `id` returned by the list workspaces endpoint.
      security:
      - API key: []
      responses:
        '200':
          description: One page of contact summaries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  contacts:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The contact ID.
                        type:
                          type: string
                          enum:
                          - personal
                          - business
                          description: Whether the contact belongs to a personal workspace (`personal`) or a team workspace (`business`).
                        full_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The contact's full name from the card, or `null` when no name is available.
                        job_title:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The contact's job title.
                        company_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The name of the contact's company.
                        created_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the contact record was created, as an ISO 8601 timestamp.
                        updated_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the contact record was last updated.
                        workspace_id:
                          type: string
                          description: The ID of the workspace containing this contact.
                      required:
                      - id
                      - type
                      - full_name
                      - job_title
                      - company_name
                      - created_at
                      - updated_at
                      - workspace_id
                      additionalProperties: false
                    description: Contact summaries for this page. Empty when no contacts match the request.
                  has_more:
                    type: boolean
                    description: Whether another page of contacts is available.
                  next_cursor:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`.
                  total_count:
                    anyOf:
                    - type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    - type: 'null'
                    description: The total number of contacts matching the filters across all pages. Returned on the first page; `null` on subsequent pages.
                required:
                - contacts
                - has_more
                - next_cursor
                - total_count
                additionalProperties: false
                description: One page of contact summaries.
              examples:
                example1:
                  value:
                    contacts:
                    - id: contact-id
                      type: personal
                      full_name: Jane Doe
                      job_title: Designer
                      company_name: Example
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      workspace_id: workspace-id
                    has_more: true
                    next_cursor: cursor-token
                    total_count: 42
                example2:
                  value:
                    contacts:
                    - id: contact-id-2
                      type: personal
                      full_name: Jane Doe
                      job_title: Designer
                      company_name: Example
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      workspace_id: workspace-id
                    has_more: true
                    next_cursor: opaque-next-page
                    total_count: null
                example3:
                  value:
                    contacts:
                    - id: contact-id-final
                      type: personal
                      full_name: null
                      job_title: null
                      company_name: null
                      created_at: '2026-10-01T00:00:00.000Z'
                      updated_at: '2026-10-01T00:00:00.000Z'
                      workspace_id: workspace-id
                    has_more: false
                    next_cursor: null
                    total_count: null
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '404':
          description: Not found - The workspace was not found or access was denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Not found - The workspace was not found or access was denied
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
  /v1/workspaces/{workspace_id}/contacts/{contact_id}:
    get:
      operationId: getContact
      summary: Get contact
      tags:
      - Contacts
      description: |-
        Gets a contact from the specified workspace, including contact details, tags, saved contact notes, linked note metadata, and capture context. Personal contacts must belong to the key owner. Business owners, admins, and members can retrieve a visible business contact when its ID is known; business members cannot discover these IDs through the list endpoint.

        Missing contacts and inaccessible workspaces return `404`.

        Requires the `blinq:contacts:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: workspace_id
        required: true
        description: The ID of the workspace containing the contact. Use the `workspace_id` returned when listing contacts.
      - schema:
          type: string
          minLength: 1
        in: path
        name: contact_id
        required: true
        description: The contact ID.
      security:
      - API key: []
      responses:
        '200':
          description: The requested contact.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The contact ID.
                  workspace_id:
                    type: string
                    description: The ID of the workspace used to retrieve the contact.
                  type:
                    type: string
                    enum:
                    - personal
                    - business
                    description: Whether the contact belongs to a personal workspace (`personal`) or a team workspace (`business`).
                  first_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's first name, or `null` when no first name is saved.
                  middle_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's middle name.
                  last_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's last name, or `null` when no last name is saved.
                  full_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's full name, or `null` when no name is saved.
                  preferred_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The name the contact prefers to use.
                  pronouns:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's pronouns.
                  job_title:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's job title.
                  company_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The name of the contact's company.
                  department:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's department within their company.
                  headline:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The contact's profile headline.
                  avatar_url:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The URL of the contact's profile image, or `null` when there is none.
                  company_logo_url:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The URL of the contact's company logo, or `null` when there is none.
                  emails:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The saved value of the contact field.
                        label:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved.
                      required:
                      - value
                      - label
                      additionalProperties: false
                    description: The contact's email addresses and their labels.
                  phone_numbers:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The saved value of the contact field.
                        label:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved.
                        country_code:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The stored country code. Values can be a region code such as `US` or a calling code such as `+1`.
                        extension:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The phone number extension.
                      required:
                      - value
                      - label
                      - country_code
                      - extension
                      additionalProperties: false
                    description: The contact's phone numbers and their labels, country codes, and extensions.
                  urls:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The saved value of the contact field.
                        label:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved.
                      required:
                      - value
                      - label
                      additionalProperties: false
                    description: The contact's website and social profile URLs and their labels.
                  addresses:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The saved value of the contact field.
                        label:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: A saved label, such as `Work`, `Home`, or a custom label. `null` when none is saved.
                      required:
                      - value
                      - label
                      additionalProperties: false
                    description: The contact's postal addresses as text values with labels.
                  tags:
                    type: array
                    items:
                      type: object
                      properties:
                        value:
                          type: string
                          description: The tag text.
                      required:
                      - value
                      additionalProperties: false
                    description: Tags assigned to the contact.
                  contact_notes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The contact note ID.
                        text:
                          type: string
                          description: The saved text of the contact note. Empty saved text is preserved.
                        created_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the contact note was created, as an ISO 8601 timestamp.
                      required:
                      - id
                      - text
                      - created_at
                      additionalProperties: false
                    description: Text notes saved on the contact.
                  linked_notes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the linked note.
                        title:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The custom title, otherwise the generated title, or `null` when it has neither.
                        created_at:
                          type: string
                          format: date-time
                          pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          description: When the user's device created the note, as an ISO 8601 timestamp.
                        type:
                          type: string
                          enum:
                          - voice_note
                          - phone_call
                          - text
                          description: 'How the linked note was captured: a recorded `voice_note`, a recorded `phone_call`, or a typed `text` note.'
                      required:
                      - id
                      - title
                      - created_at
                      - type
                      additionalProperties: false
                    description: Metadata for notes linked to the contact, including each note's ID, title, creation time, and type.
                  capture_context:
                    anyOf:
                    - type: object
                      properties:
                        recorded_at:
                          anyOf:
                          - type: string
                            format: date-time
                            pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          - type: 'null'
                          description: The saved capture timestamp as ISO 8601, or `null` when unavailable. For business contacts, uses the selected recipient capture time, then recipient sharing time, contact sharing time, or contact capture time, in that order.
                        location:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The location recorded when the contact was captured.
                        cardholder_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The name on the recipient card, or `null` when unavailable. For business contacts, uses the earliest recipient by capture time (sharing time if capture time is absent); legacy recipients missing both times sort first. Falls back to the contact referrer card when no recipient card is recorded. This does not identify a verified meeting participant.
                      required:
                      - recorded_at
                      - location
                      - cardholder_name
                      additionalProperties: false
                    - type: 'null'
                    description: Saved capture metadata, not evidence of a meeting. For business contacts, location and cardholder refer to the selected earliest recipient. `null` means no capture metadata is available.
                  created_at:
                    anyOf:
                    - type: string
                      format: date-time
                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    - type: 'null'
                    description: When the contact was created, as an ISO 8601 timestamp.
                  updated_at:
                    anyOf:
                    - type: string
                      format: date-time
                      pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                    - type: 'null'
                    description: When the contact was last updated, as an ISO 8601 timestamp.
                required:
                - id
                - workspace_id
                - type
                - first_name
                - middle_name
                - last_name
                - full_name
                - preferred_name
                - pronouns
                - job_title
                - company_name
                - department
                - headline
                - avatar_url
                - company_logo_url
                - emails
                - phone_numbers
                - urls
                - addresses
                - tags
                - contact_notes
                - linked_notes
                - capture_context
                - created_at
                - updated_at
                additionalProperties: false
                description: The requested contact.
              example:
                id: contact-id
                workspace_id: workspace-id
                type: business
                first_name: Jane
                middle_name: null
                last_name: Doe
                full_name: Jane Doe
                preferred_name: null
                pronouns: null
                job_title: Designer
                company_name: Example
                department: null
                headline: null
                avatar_url: https://example.com/avatar.png
                company_logo_url: null
                emails:
                - value: jane@example.com
                  label: Work
                phone_numbers:
                - value: '5550100'
                  label: null
                  country_code: '+1'
                  extension: null
                urls:
                - value: https://example.com
                  label: Website
                addresses:
                - value: 123 Example St, Melbourne
                  label: Office
                tags:
                - value: Customer
                contact_notes:
                - id: contact-note-id
                  text: Follow up next week.
                  created_at: '2026-10-01T00:00:00.000Z'
                linked_notes:
                - id: note-id
                  title: Meeting notes
                  created_at: '2026-10-01T00:00:00.000Z'
                  type: voice_note
                capture_context:
                  recorded_at: '2026-10-01T00:00:00.000Z'
                  location: Melbourne
                  cardholder_name: Sam Smith
                created_at: '2026-10-01T00:00:00.000Z'
                updated_at: '2026-10-01T00:00:00.000Z'
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '404':
          description: Not found - The contact was not found or access was denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Not found - The contact was not found or access was denied
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
  /v1/workspaces/{workspace_id}/cards:
    get:
      operationId: listCards
      summary: List cards
      tags:
      - Cards
      description: |-
        Returns a paginated list of lightweight card summaries from your personal workspace or a business workspace you own or administer. Other workspaces, including business workspaces where you are only a member, return `404`.

        Deleted cards, drafts, and card templates are excluded. Each summary includes the public sharing URL for the card.

        Cards are sorted by creation time, newest first, with the card ID as a tie-breaker, so pages are deterministic. Cursors are bound to the requesting key owner and workspace.

        Requires the `blinq:cards:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: query
        name: cursor
        required: false
        description: The `next_cursor` returned by the previous response. Omit for the first page. Keep the workspace unchanged between pages.
      - schema:
          default: 25
          type: integer
          exclusiveMinimum: 0
          maximum: 50
        in: query
        name: limit
        required: false
        description: The maximum number of cards to return per page.
      - schema:
          type: string
          minLength: 1
        in: path
        name: workspace_id
        required: true
        description: The workspace ID. Use an `id` returned by the list workspaces endpoint.
      security:
      - API key: []
      responses:
        '200':
          description: One page of card summaries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  cards:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The card ID.
                        workspace_id:
                          type: string
                          description: The ID of the workspace containing the card.
                        url:
                          type: string
                          description: The public sharing URL for the card. Anyone with the link can view the card.
                        first_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The first name saved on the card, or `null` when none is saved.
                        last_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The last name saved on the card, or `null` when none is saved.
                        job_title:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The job title saved on the card.
                        company_name:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The company name saved on the card.
                        department:
                          anyOf:
                          - type: string
                          - type: 'null'
                          description: The department saved on the card.
                      required:
                      - id
                      - workspace_id
                      - url
                      - first_name
                      - last_name
                      - job_title
                      - company_name
                      - department
                      additionalProperties: false
                      description: The requested card summary.
                      example:
                        id: card-id
                        workspace_id: workspace-id
                        url: https://blinq.me/card-id
                        first_name: Jane
                        last_name: Doe
                        job_title: Designer
                        company_name: Example
                        department: null
                    description: Card summaries for this page. Empty when the workspace has no visible cards.
                  has_more:
                    type: boolean
                    description: Whether another page of cards is available.
                  next_cursor:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The cursor for the next page. When `has_more` is `true`, pass this value as `cursor`. Otherwise, this value is `null`.
                  total_count:
                    anyOf:
                    - type: integer
                      minimum: 0
                      maximum: 9007199254740991
                    - type: 'null'
                    description: The total number of visible cards in the workspace. Returned on the first page; `null` on subsequent pages.
                required:
                - cards
                - has_more
                - next_cursor
                - total_count
                additionalProperties: false
                description: One page of card summaries.
              example:
                cards:
                - id: card-id
                  workspace_id: workspace-id
                  url: https://blinq.me/card-id
                  first_name: Jane
                  last_name: Doe
                  job_title: Designer
                  company_name: Example
                  department: null
                has_more: false
                next_cursor: null
                total_count: 1
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '404':
          description: Not found - The workspace was not found or access was denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Not found - The workspace was not found or access was denied
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
  /v1/workspaces/{workspace_id}/cards/{card_id}:
    get:
      operationId: getCard
      summary: Get card
      tags:
      - Cards
      description: |-
        Gets a lightweight card summary from the specified workspace, including the public sharing URL for the card. The workspace must be your personal workspace or a business workspace you own or administer.

        Missing cards, cards belonging to a different workspace, and inaccessible workspaces return `404`.

        Requires the `blinq:cards:read` scope.
      parameters:
      - schema:
          type: string
          minLength: 1
        in: path
        name: workspace_id
        required: true
        description: The ID of the workspace containing the card. Use an `id` from list workspaces.
      - schema:
          type: string
          minLength: 1
        in: path
        name: card_id
        required: true
        description: The card ID.
      security:
      - API key: []
      responses:
        '200':
          description: The requested card summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The card ID.
                  workspace_id:
                    type: string
                    description: The ID of the workspace containing the card.
                  url:
                    type: string
                    description: The public sharing URL for the card. Anyone with the link can view the card.
                  first_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The first name saved on the card, or `null` when none is saved.
                  last_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The last name saved on the card, or `null` when none is saved.
                  job_title:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The job title saved on the card.
                  company_name:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The company name saved on the card.
                  department:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: The department saved on the card.
                required:
                - id
                - workspace_id
                - url
                - first_name
                - last_name
                - job_title
                - company_name
                - department
                additionalProperties: false
                description: The requested card summary.
              example:
                id: card-id
                workspace_id: workspace-id
                url: https://blinq.me/card-id
                first_name: Jane
                last_name: Doe
                job_title: Designer
                company_name: Example
                department: null
        '400':
          description: Bad request - Invalid query parameters or body. See `details` for each failing field
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Bad request - Invalid query parameters or body. See `details` for each failing field
              example:
                status: 400
                error: Bad Request
                code: invalid_request
                message: The request is invalid.
                request_id: req-1
                details:
                - path: limit
                  message: 'Too big: expected number to be <=50'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Unauthorized - Missing or invalid API key
              example:
                status: 401
                error: Unauthorized
                code: unauthorized
                message: Missing or invalid API key.
                request_id: req-1
        '403':
          description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Forbidden - Missing scope, insufficient permission, or the plan does not include this operation
              examples:
                example1:
                  value:
                    status: 403
                    error: Forbidden
                    code: forbidden
                    message: You do not have access to the requested resource.
                    request_id: req-1
                example2:
                  value:
                    status: 403
                    error: Forbidden
                    code: plan_required
                    message: The API key owner must have a Blinq Pro or Business plan to use this endpoint.
                    request_id: req-1
        '404':
          description: Not found - The card was not found or access was denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                    description: The HTTP status code of the response.
                  error:
                    type: string
                    description: The HTTP status name, such as `Bad Request`.
                  code:
                    type: string
                    enum:
                    - invalid_request
                    - unauthorized
                    - forbidden
                    - plan_required
                    - not_found
                    - unsupported_media_type
                    - rate_limited
                    - internal_error
                    - upstream_unavailable
                    description: A machine-readable code identifying the error. Use this value for programmatic error handling.
                  message:
                    type: string
                    description: A human-readable description. Wording may change; branch on `code` instead.
                  request_id:
                    type: string
                    description: The unique ID of this request, also returned as the `X-Request-Id` header. Include it when contacting support.
                  details:
                    description: Additional validation errors, when available.
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: The parameter or body field that failed validation, such as `limit`. Empty for errors that apply to the whole request.
                        message:
                          type: string
                          description: A description of the validation error.
                      required:
                      - path
                      - message
                      additionalProperties: false
                required:
                - status
                - error
                - code
                - message
                - request_id
                additionalProperties: false
                description: Not found - The card was not found or access was denied
              example:
                status: 404
                error: Not Found
                code: not_found
                message: The requested resource was not found.
                request_id: req-1
servers:
- url: https://api.blinq.me
tags:
- name: Contacts
  description: |-
    List contact summaries or get contact details, saved contact notes, and linked note metadata.

    Contact lists include personal contacts and contacts in business workspaces the authenticated user owns or administers. Business members receive an empty list, but can retrieve a visible business contact by known ID.

    Requires the `blinq:contacts:read` scope.
- name: Cards
  description: |-
    List or get lightweight card summaries: the name, title, company, department, and public sharing URL on each card.

    Card routes are scoped to one workspace: your personal workspace or a business workspace you own or administer. Business members cannot read team cards.

    Requires the `blinq:cards:read` scope.
- name: Notes
  description: |-
    List note metadata, get note content and transcripts, search notes, or generate answers with citations.

    Only notes owned by the authenticated user are accessible.

    Requires the `blinq:notes:read` scope.
- name: Workspaces
  description: |-
    List every workspace the authenticated user belongs to, with its type and their role.

    Use a known workspace ID directly, or discover it here. Business contact listing requires owner or admin; retrieving a visible contact by known ID also allows members.

    Requires the `blinq:identity:read` scope.
- name: Me
  description: |-
    Identify the user the supplied API key acts as, with their ID and sign-in email.

    Confirm whose account an integration is accessing before listing workspaces or fetching data.

    Requires the `blinq:identity:read` scope.