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

# Embedding

> Vectorize content with an Isaacus embedding model.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/isaacus/openapi.documented.yml post /embeddings
openapi: 3.1.0
info:
  title: Isaacus API
  version: 0.8.2
  description: A RESTful API for using Isaacus legal models, data and other solutions.
  termsOfService: https://isaacus.com/terms
  contact:
    name: Isaacus Support
    url: https://isaacus.com/support
    email: support@isaacus.com
  license:
    name: Apache 2.0
    url: https://github.com/isaacus-dev/openapi/blob/main/LICENSE
servers:
  - url: https://api.isaacus.com/v1
security:
  - APIKeyBearerTokenAuth: []
tags:
  - name: Enrichments
    description: Enrich documents with an Isaacus enrichment model.
  - name: Embeddings
    description: Vectorize content with an Isaacus embedding model.
  - name: Rerankings
    description: >-
      Score and rank documents by their relevance to queries with an Isaacus
      reranker.
  - name: Extractions
    description: Extract information from documents with an Isaacus extraction model.
  - name: Classifications
    description: Classify documents with an Isaacus classification model.
externalDocs:
  url: https://docs.isaacus.com/api-reference
  description: Reference documentation for the Isaacus API.
paths:
  /embeddings:
    post:
      tags:
        - Embeddings
      summary: Embedding
      description: Vectorize content with an Isaacus embedding model.
      operationId: CreateEmbeddings
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
        required: true
      responses:
        '200':
          description: Embeddings of texts produced by an Isaacus embedding model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
              examples:
                example:
                  value:
                    embeddings:
                      - index: 0
                        embedding:
                          - -0.0258
                          - 0.02062
                          - -0.0114
                      - index: 1
                        embedding:
                          - -0.0358
                          - -0.0128
                          - 0.00251
                    usage:
                      input_tokens: 42
        '400':
          description: The request was invalid or could not be processed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationError'
              examples:
                Validation error:
                  summary: Validation error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#400-validation-error
                    title: Validation error
                    status: 400
                    detail: The request was invalid or could not be processed.
                    instance: null
                Embedding input too large error:
                  summary: Embedding input too large error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#400-validation-error
                    title: Embedding input too large error
                    status: 400
                    detail: >-
                      The input to the embedding model exceeds the maximum
                      allowed size.
                    instance: null
                Unsupported embedding dimension error:
                  summary: Unsupported embedding dimension error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#400-validation-error
                    title: Unsupported embedding dimension error
                    status: 400
                    detail: >-
                      The provided embedding dimension is not supported by the
                      model.
                    instance: null
                Unsupported embedding task error:
                  summary: Unsupported embedding task error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#400-validation-error
                    title: Unsupported embedding task error
                    status: 400
                    detail: The provided embedding task is not supported by the model.
                    instance: null
        '401':
          description: >-
            The API key you provided does not exist, is expired or revoked, or
            is not authorized to access this resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/UnauthorizedAPIKeyError'
              examples:
                Unauthorized API key error:
                  summary: Unauthorized API key error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#401-not-authenticated
                    title: Unauthorized API key error
                    status: 401
                    detail: >-
                      The API key you provided does not exist, is expired or
                      revoked, or is not authorized to access this resource.
                    instance: null
                Incorrect API key error:
                  summary: Incorrect API key error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#401-not-authenticated
                    title: Incorrect API key error
                    status: 401
                    detail: >-
                      The API key you provided does not exist or is expired or
                      revoked.
                    instance: null
        '402':
          description: >-
            Your account is overdue, please pay any outstanding invoices to
            continue using our services.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/AccountOverdueError'
              examples:
                Account overdue error:
                  summary: Account overdue error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#402-payment-required
                    title: Account overdue error
                    status: 402
                    detail: >-
                      Your account is overdue, please pay any outstanding
                      invoices to continue using our services.
                    instance: null
        '403':
          description: You are not allowed to access this resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/AccessForbiddenError'
              examples:
                Access forbidden error:
                  summary: Access forbidden error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#403-access-forbidden
                    title: Access forbidden error
                    status: 403
                    detail: You are not allowed to access this resource.
                    instance: null
                No subscription error:
                  summary: No subscription error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#403-access-forbidden
                    title: No subscription error
                    status: 403
                    detail: >-
                      You do not have an active subscription to our zero-flat
                      fee, usage-based API plan.
                    instance: null
        '413':
          description: The request is larger than the server is willing or able to process.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/RequestTooLargeError'
              examples:
                Request too large error:
                  summary: Request too large error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#413-request-too-large
                    title: Request too large error
                    status: 413
                    detail: >-
                      The request is larger than the server is willing or able
                      to process.
                    instance: null
        '500':
          description: An unexpected error occurred while processing the request.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
              examples:
                Internal server error:
                  summary: Internal server error
                  value:
                    type: >-
                      https://docs.isaacus.com/api-reference/errors#500-internal-server-error
                    title: Internal server error
                    status: 500
                    detail: An unexpected error occurred while processing the request.
                    instance: null
      deprecated: false
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import Isaacus from 'isaacus';

            const client = new Isaacus({
              apiKey: process.env['ISAACUS_API_KEY'], // This is the default and can be omitted
            });

            const embeddingResponse = await client.embeddings.create({
              model: 'kanon-2-embedder',
              texts: [
                'Are restraints of trade enforceable under English law?',
                'What is a non-compete clause?',
              ],
            });

            console.log(embeddingResponse.embeddings);
        - lang: Python
          source: |-
            import os
            from isaacus import Isaacus

            client = Isaacus(
                api_key=os.environ.get("ISAACUS_API_KEY"),  # This is the default and can be omitted
            )
            embedding_response = client.embeddings.create(
                model="kanon-2-embedder",
                texts=["Are restraints of trade enforceable under English law?", "What is a non-compete clause?"],
            )
            print(embedding_response.embeddings)
components:
  schemas:
    EmbeddingRequest:
      properties:
        model:
          type: string
          const: kanon-2-embedder
          description: >-
            The ID of the [model](https://docs.isaacus.com/models#embedding) to
            use for embedding.
          examples:
            - kanon-2-embedder
        texts:
          oneOf:
            - items:
                type: string
              type: array
            - type: string
          description: |-
            The text or array of texts to embed.

            Each text must contain at least one non-whitespace character.

            No more than 128 texts can be embedded in a single request.
          examples:
            - - Are restraints of trade enforceable under English law?
              - What is a non-compete clause?
        task:
          type:
            - 'null'
            - string
          enum:
            - retrieval/query
            - retrieval/document
            - null
          description: >-
            The task the embeddings will be used for.


            `retrieval/query` is meant for queries and statements, and
            `retrieval/document` is meant for anything to be retrieved using
            query embeddings.


            If `null`, which is the default setting, embeddings will not be
            optimized for any particular task.
          examples:
            - retrieval/query
        overflow_strategy:
          type:
            - 'null'
            - string
          enum:
            - drop_end
            - null
          description: >-
            The strategy to employ when content exceeds the model's maximum
            input length.


            `drop_end`, which is the default setting, drops tokens from the end
            of the content exceeding the limit.


            If `null`, an error will be raised if any content exceeds the
            model's maximum input length.
          default: drop_end
          examples:
            - drop_end
        dimensions:
          oneOf:
            - type: integer
              minimum: 1
              title: Positive integer
              description: A whole number greater than or equal to 1.
              examples:
                - 1
            - type: 'null'
          description: >-
            The number of dimensions the embeddings should have, not exceeding
            the maximum dimensions of the model.


            If `null`, the model's default dimensions will be used.
          examples:
            - 1792
      type: object
      required:
        - model
        - texts
      title: Embedding request
      description: A request to vectorize content with an Isaacus embedding model.
      examples:
        - model: kanon-2-embedder
          texts:
            - Are restraints of trade enforceable under English law?
            - What is a non-compete clause?
          task: retrieval/query
    EmbeddingResponse:
      properties:
        embeddings:
          items:
            $ref: '#/components/schemas/Embedding'
          type: array
          description: The embeddings of the inputs.
          examples:
            - - index: 0
                embedding:
                  - -0.0258
                  - 0.02062
                  - -0.0114
              - index: 1
                embedding:
                  - -0.0358
                  - -0.0128
                  - 0.00251
        usage:
          $ref: '#/components/schemas/EmbeddingUsage'
      type: object
      required:
        - embeddings
        - usage
      title: Embedding response
      examples:
        - embeddings:
            - index: 0
              embedding:
                - -0.0258
                - 0.02062
                - -0.0114
            - index: 1
              embedding:
                - -0.0358
                - -0.0128
                - 0.00251
          usage:
            input_tokens: 42
    ValidationError:
      properties:
        type:
          type: string
          minLength: 1
          title: Non-empty string
          description: A URI reference that identifies the problem type.
          default: https://docs.isaacus.com/api-reference/errors#400-validation-error
          examples:
            - https://docs.isaacus.com/api-reference/errors#400-validation-error
        title:
          type: string
          minLength: 1
          title: Non-empty string
          description: A short, human-readable summary of the problem type.
          default: Validation error
          examples:
            - Validation error
        status:
          type: integer
          const: 400
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          default: 400
          examples:
            - 400
        detail:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              default: The request was invalid or could not be processed.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional human-readable explanation specific to this occurrence
            of the problem.
          default: The request was invalid or could not be processed.
          examples:
            - The request was invalid or could not be processed.
        instance:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional URI reference that identifies the specific occurrence of
            the problem.
          examples:
            - null
      type: object
      required: []
      title: Validation error
      description: An RFC 7807 problem detail object.
      examples:
        - type: https://docs.isaacus.com/api-reference/errors#400-validation-error
          title: Validation error
          status: 400
          detail: The request was invalid or could not be processed.
          instance: null
    UnauthorizedAPIKeyError:
      properties:
        type:
          type: string
          minLength: 1
          title: Non-empty string
          description: A URI reference that identifies the problem type.
          default: https://docs.isaacus.com/api-reference/errors#401-not-authenticated
          examples:
            - >-
              https://docs.isaacus.com/api-reference/errors#401-not-authenticated
        title:
          type: string
          minLength: 1
          title: Non-empty string
          description: A short, human-readable summary of the problem type.
          default: Unauthorized API key error
          examples:
            - Unauthorized API key error
        status:
          type: integer
          const: 401
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          default: 401
          examples:
            - 401
        detail:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              default: >-
                The API key you provided does not exist, is expired or revoked,
                or is not authorized to access this resource.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional human-readable explanation specific to this occurrence
            of the problem.
          default: >-
            The API key you provided does not exist, is expired or revoked, or
            is not authorized to access this resource.
          examples:
            - >-
              The API key you provided does not exist, is expired or revoked, or
              is not authorized to access this resource.
        instance:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional URI reference that identifies the specific occurrence of
            the problem.
          examples:
            - null
      type: object
      required: []
      title: Unauthorized API key error
      description: An RFC 7807 problem detail object.
      examples:
        - type: https://docs.isaacus.com/api-reference/errors#401-not-authenticated
          title: Unauthorized API key error
          status: 401
          detail: >-
            The API key you provided does not exist, is expired or revoked, or
            is not authorized to access this resource.
          instance: null
    AccountOverdueError:
      properties:
        type:
          type: string
          minLength: 1
          title: Non-empty string
          description: A URI reference that identifies the problem type.
          default: https://docs.isaacus.com/api-reference/errors#402-payment-required
          examples:
            - https://docs.isaacus.com/api-reference/errors#402-payment-required
        title:
          type: string
          minLength: 1
          title: Non-empty string
          description: A short, human-readable summary of the problem type.
          default: Account overdue error
          examples:
            - Account overdue error
        status:
          type: integer
          const: 402
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          default: 402
          examples:
            - 402
        detail:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              default: >-
                Your account is overdue, please pay any outstanding invoices to
                continue using our services.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional human-readable explanation specific to this occurrence
            of the problem.
          default: >-
            Your account is overdue, please pay any outstanding invoices to
            continue using our services.
          examples:
            - >-
              Your account is overdue, please pay any outstanding invoices to
              continue using our services.
        instance:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional URI reference that identifies the specific occurrence of
            the problem.
          examples:
            - null
      type: object
      required: []
      title: Account overdue error
      description: An RFC 7807 problem detail object.
      examples:
        - type: https://docs.isaacus.com/api-reference/errors#402-payment-required
          title: Account overdue error
          status: 402
          detail: >-
            Your account is overdue, please pay any outstanding invoices to
            continue using our services.
          instance: null
    AccessForbiddenError:
      properties:
        type:
          type: string
          minLength: 1
          title: Non-empty string
          description: A URI reference that identifies the problem type.
          default: https://docs.isaacus.com/api-reference/errors#403-access-forbidden
          examples:
            - https://docs.isaacus.com/api-reference/errors#403-access-forbidden
        title:
          type: string
          minLength: 1
          title: Non-empty string
          description: A short, human-readable summary of the problem type.
          default: Access forbidden error
          examples:
            - Access forbidden error
        status:
          type: integer
          const: 403
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          default: 403
          examples:
            - 403
        detail:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              default: You are not allowed to access this resource.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional human-readable explanation specific to this occurrence
            of the problem.
          default: You are not allowed to access this resource.
          examples:
            - You are not allowed to access this resource.
        instance:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional URI reference that identifies the specific occurrence of
            the problem.
          examples:
            - null
      type: object
      required: []
      title: Access forbidden error
      description: An RFC 7807 problem detail object.
      examples:
        - type: https://docs.isaacus.com/api-reference/errors#403-access-forbidden
          title: Access forbidden error
          status: 403
          detail: You are not allowed to access this resource.
          instance: null
    RequestTooLargeError:
      properties:
        type:
          type: string
          minLength: 1
          title: Non-empty string
          description: A URI reference that identifies the problem type.
          default: https://docs.isaacus.com/api-reference/errors#413-request-too-large
          examples:
            - >-
              https://docs.isaacus.com/api-reference/errors#413-request-too-large
        title:
          type: string
          minLength: 1
          title: Non-empty string
          description: A short, human-readable summary of the problem type.
          default: Request too large error
          examples:
            - Request too large error
        status:
          type: integer
          const: 413
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          default: 413
          examples:
            - 413
        detail:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              default: >-
                The request is larger than the server is willing or able to
                process.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional human-readable explanation specific to this occurrence
            of the problem.
          default: The request is larger than the server is willing or able to process.
          examples:
            - >-
              The request is larger than the server is willing or able to
              process.
        instance:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional URI reference that identifies the specific occurrence of
            the problem.
          examples:
            - null
      type: object
      required: []
      title: Request too large error
      description: An RFC 7807 problem detail object.
      examples:
        - type: https://docs.isaacus.com/api-reference/errors#413-request-too-large
          title: Request too large error
          status: 413
          detail: The request is larger than the server is willing or able to process.
          instance: null
    InternalServerError:
      properties:
        type:
          type: string
          minLength: 1
          title: Non-empty string
          description: A URI reference that identifies the problem type.
          default: >-
            https://docs.isaacus.com/api-reference/errors#500-internal-server-error
          examples:
            - >-
              https://docs.isaacus.com/api-reference/errors#500-internal-server-error
        title:
          type: string
          minLength: 1
          title: Non-empty string
          description: A short, human-readable summary of the problem type.
          default: Internal server error
          examples:
            - Internal server error
        status:
          type: integer
          const: 500
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem.
          default: 500
          examples:
            - 500
        detail:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              default: An unexpected error occurred while processing the request.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional human-readable explanation specific to this occurrence
            of the problem.
          default: An unexpected error occurred while processing the request.
          examples:
            - An unexpected error occurred while processing the request.
        instance:
          oneOf:
            - type: string
              minLength: 1
              title: Non-empty string
              description: A string with at least one character.
              examples:
                - A string.
            - type: 'null'
          description: >-
            An optional URI reference that identifies the specific occurrence of
            the problem.
          examples:
            - null
      type: object
      required: []
      title: Internal server error
      description: An RFC 7807 problem detail object.
      examples:
        - type: >-
            https://docs.isaacus.com/api-reference/errors#500-internal-server-error
          title: Internal server error
          status: 500
          detail: An unexpected error occurred while processing the request.
          instance: null
    Embedding:
      properties:
        index:
          type: integer
          minimum: 0
          title: Non-negative integer
          description: >-
            The position of the content in the input array of contents, starting
            from `0` (and, therefore, ending at the number of contents minus
            `1`).
          examples:
            - 0
        embedding:
          items:
            type: number
          type: array
          description: >-
            The embedding of the content represented as an array of floating
            point numbers.
          examples:
            - - -0.0258
              - 0.02062
              - -0.0114
      type: object
      required:
        - index
        - embedding
      title: Embedding
      examples:
        - index: 0
          embedding:
            - -0.0258
            - 0.02062
            - -0.0114
    EmbeddingUsage:
      properties:
        input_tokens:
          type: integer
          minimum: 1
          title: Positive integer
          description: The number of tokens inputted to the model.
          examples:
            - 42
      type: object
      required:
        - input_tokens
      title: Embedding usage
      description: >-
        Statistics about the usage of resources in the process of embedding the
        inputs.
      examples:
        - input_tokens: 42
  securitySchemes:
    APIKeyBearerTokenAuth:
      type: http
      description: >-
        An Isaacus-issued API key passed as a bearer token via the
        `Authorization` header in the format `Authorization: Bearer
        YOUR_API_KEY`.
      scheme: bearer
      bearerFormat: iuak_v1_APIKEYSECRET_CHECKSUM

````