Vendasta Knowledge API

openapi: 3.2.0
info:
  description: Manage the knowledge available to AI Employees on your accounts.
  title: AI Knowledge API
  version: 2.0.0
servers:
- description: Production
  url: https://prod.apigateway.co/grpc
tags:
- name: Knowledge
paths:
  /v1/knowledge/file-upload:
    post:
      description: 'Get a signed URL and an upload handle for a direct upload of one file to storage. Then use Upsert Knowledge to ingest the file as knowledge.


        All write requests (Upsert Knowledge, Create Knowledge File Upload, and Remove Knowledge together) share one rate limit. The write budget of each account group refills continuously, at 10 requests per minute. A partner-wide ceiling of 100 requests per minute applies to all account groups together. A request over either limit fails with HTTP 429. Writes to the partner''s own knowledge base count only against the partner-wide ceiling.


        Required OAuth2 scopes: `knowledge`'
      operationId: Knowledge_CreateKnowledgeFileUpload
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2CreateKnowledgeFileUploadRequest'
        description: 'Request to issue a signed URL and handle for uploading a single knowledge

          file directly to storage.'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2CreateKnowledgeFileUploadResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - knowledge
      summary: Create Knowledge File Upload
      tags:
      - Knowledge
  /v1/knowledge/list:
    post:
      description: 'List the knowledge sources in an account''s or partner''s knowledge base, with pagination.


        Required OAuth2 scopes: `knowledge` or `knowledge:read`'
      operationId: Knowledge_ListKnowledge
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2ListKnowledgeRequest'
        description: 'Request to list the knowledge sources in a namespace''s knowledge base,

          optionally filtered to one AI Employee.'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2ListKnowledgeResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - knowledge
        - knowledge:read
      summary: List Knowledge
      tags:
      - Knowledge
  /v1/knowledge/remove:
    post:
      description: 'Delete a knowledge source in an account''s or partner''s knowledge base, or unlink the source from the specified AI Employees.


        All write requests (Upsert Knowledge, Create Knowledge File Upload, and Remove Knowledge together) share one rate limit. The write budget of each account group refills continuously, at 10 requests per minute. A partner-wide ceiling of 100 requests per minute applies to all account groups together. A request over either limit fails with HTTP 429. Writes to the partner''s own knowledge base count only against the partner-wide ceiling.


        Required OAuth2 scopes: `knowledge`'
      operationId: Knowledge_RemoveKnowledge
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2RemoveKnowledgeRequest'
        description: 'Request to remove a knowledge source from a namespace''s knowledge base,

          either by deleting it or by unlinking it from specific AI Employees.'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2RemoveKnowledgeResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - knowledge
      summary: Remove Knowledge
      tags:
      - Knowledge
  /v1/knowledge/status:
    post:
      description: 'Get the processing status of a single knowledge source in an account''s or partner''s knowledge base.


        Required OAuth2 scopes: `knowledge` or `knowledge:read`'
      operationId: Knowledge_GetKnowledgeStatus
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2GetKnowledgeStatusRequest'
        description: Request to look up the processing status of a single knowledge source.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2GetKnowledgeStatusResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - knowledge
        - knowledge:read
      summary: Get Knowledge Status
      tags:
      - Knowledge
  /v1/knowledge/upsert:
    post:
      description: 'Create or update a knowledge source in an account''s or partner''s knowledge base. You can also link the source to an AI Employee.


        All write requests (Upsert Knowledge, Create Knowledge File Upload, and Remove Knowledge together) share one rate limit. The write budget of each account group refills continuously, at 10 requests per minute. A partner-wide ceiling of 100 requests per minute applies to all account groups together. A request over either limit fails with HTTP 429. Writes to the partner''s own knowledge base count only against the partner-wide ceiling.


        Required OAuth2 scopes: `knowledge`'
      operationId: Knowledge_UpsertKnowledge
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v2UpsertKnowledgeRequest'
        description: 'Request to create or update a knowledge source and optionally link it to an

          AI Employee.'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v2UpsertKnowledgeResponse'
          description: A successful response.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
          description: An unexpected error response.
      security:
      - OAuth2:
        - knowledge
      summary: Upsert Knowledge
      tags:
      - Knowledge
components:
  schemas:
    rpcStatus:
      properties:
        code:
          format: int32
          type: integer
        details:
          items:
            $ref: '#/components/schemas/protobufAny'
          type: array
        message:
          type: string
      type: object
    v2TrainingState:
      default: TRAINING_STATE_INVALID
      description: "The processing state of a knowledge source's content.\n\n - TRAINING_STATE_QUEUED: The content is queued for processing. It is not yet available to AI\nEmployees.\n - TRAINING_STATE_IN_PROGRESS: Processing started and is not complete.\n - TRAINING_STATE_DONE: Processing completed successfully. The content is available to AI\nEmployees.\n - TRAINING_STATE_ERRORED: Processing failed. See the error_code on TrainingStatus for the reason."
      enum:
      - TRAINING_STATE_INVALID
      - TRAINING_STATE_QUEUED
      - TRAINING_STATE_IN_PROGRESS
      - TRAINING_STATE_DONE
      - TRAINING_STATE_ERRORED
      type: string
    vendastatypesPagedRequestOptions:
      properties:
        cursor:
          description: Optional. An opaque token from a previous response's next_cursor to retrieve the next page of results. Omit or leave empty for the first page.
          type: string
        pageSize:
          description: Optional. The maximum number of items to return per page.
          format: int64
          type: string
      type: object
    v2UnlinkMode:
      description: 'Selects unlinking the knowledge source from specific AI Employees without

        deleting it.'
      properties:
        assistantIds:
          description: 'The AI Employees to unlink the source from. Supply each assistant id

            exactly as List Assistants returns it (format: "ASSISTANT-XXXX"). The

            API rejects all other formats, including the bare id without the

            "ASSISTANT-" prefix and internal application ids. At least one id is

            required. The maximum is 100 ids in one request.'
          items:
            type: string
          type: array
      required:
      - assistantIds
      type: object
    v2DeleteMode:
      description: 'Selects the deletion of the knowledge source. This message has no fields.

        Its presence in the mode oneof is the instruction to delete.'
      type: object
    v2TextContent:
      description: Free-form text content that an integration supplies directly.
      properties:
        text:
          description: 'The text to store as knowledge. At most 100,000 characters. The count

            is in Unicode characters, not bytes. For larger reference material,

            upload a file instead.'
          type: string
      required:
      - text
      type: object
    v2TrainingStatus:
      description: 'The processing status of a knowledge source, including progress counters

        and any terminal error.'
      properties:
        completedUnits:
          description: 'The number of units that completed their processing. The value is equal

            to total_units when the processing is complete.'
          format: int64
          readOnly: true
          type: string
        errorCode:
          $ref: '#/components/schemas/v2TrainingErrorCode'
        state:
          $ref: '#/components/schemas/v2TrainingState'
        totalUnits:
          description: 'The total number of units that the processing divided the content into.

            The value is 0 when the processing of the source does not use units.'
          format: int64
          readOnly: true
          type: string
      type: object
    v2ListKnowledgeRequest:
      description: 'Request to list the knowledge sources in a namespace''s knowledge base,

        optionally filtered to one AI Employee.'
      properties:
        accountGroupId:
          description: 'The account group whose knowledge to list (format: "AG-XXXXXXXXXX").

            The calling partner must own this account.'
          type: string
        assistantId:
          description: 'Optional. When set, the response contains only the knowledge sources

            attached to this AI Employee. Supply the assistant id exactly as List

            Assistants returns it (format: "ASSISTANT-XXXX"). The API rejects all

            other formats, including the bare id without the "ASSISTANT-" prefix

            and internal application ids. An unknown assistant id returns an empty

            list.'
          type: string
        pagingOptions:
          $ref: '#/components/schemas/vendastatypesPagedRequestOptions'
        partnerId:
          description: 'The partner namespace whose knowledge to list. Must be the calling

            partner''s own partner id.'
          type: string
      type: object
    v2CreateKnowledgeFileUploadResponse:
      description: The signed URL and handle for uploading a single knowledge file.
      properties:
        expiresAt:
          description: 'The time when the upload_url and the upload_handle expire. Upload the

            bytes, and use the handle in UpsertKnowledge, before this time.'
          format: date-time
          readOnly: true
          type: string
        requiredHeaders:
          additionalProperties:
            type: string
          description: 'The HTTP headers that the PUT to upload_url must send, with no changes.

            They include the Content-Type and the X-Goog-Content-Length-Range that

            are part of the signature. Storage rejects a PUT whose headers do not

            match.'
          readOnly: true
          type: object
        uploadHandle:
          description: 'The handle that identifies the uploaded bytes. To ingest the file, pass

            this value as the upload_handle in FileContent on a subsequent

            UpsertKnowledge call. The handle is bound to the namespace and to the

            caller of this request. The API rejects the handle after expires_at,

            and under a different namespace.'
          readOnly: true
          type: string
        uploadUrl:
          description: 'The signed URL for the upload. PUT the file bytes to this URL. The URL

            is valid only until expires_at.'
          readOnly: true
          type: string
      type: object
    v2TrainingErrorCode:
      default: TRAINING_ERROR_CODE_INVALID
      description: "Machine-readable reason a knowledge source failed processing.\n\n - TRAINING_ERROR_CODE_INVALID: No error is recorded. This is the value when the processing of the\nsource did not fail (state is not TRAINING_STATE_ERRORED).\n - TRAINING_ERROR_CODE_LARGE_FILE_CONTENT: The content of the file is too large for processing.\n - TRAINING_ERROR_CODE_UNPROCESSABLE_CONTENT: The parse or the processing of the content failed. A possible cause is\na file that is defective or empty."
      enum:
      - TRAINING_ERROR_CODE_INVALID
      - TRAINING_ERROR_CODE_LARGE_FILE_CONTENT
      - TRAINING_ERROR_CODE_UNPROCESSABLE_CONTENT
      type: string
    v2ListKnowledgeResponse:
      description: A page of knowledge sources with pagination metadata.
      properties:
        knowledgeSources:
          description: The knowledge sources on this page.
          items:
            $ref: '#/components/schemas/v2KnowledgeSourceSummary'
          readOnly: true
          type: array
        pagingMetadata:
          $ref: '#/components/schemas/vendastatypesPagedResponseMetadata'
      type: object
    v2KnowledgeConfigType:
      default: KNOWLEDGE_CONFIG_TYPE_INVALID
      description: "The kind of content backing a knowledge source.\n\n - KNOWLEDGE_CONFIG_TYPE_BUSINESS_PROFILE: Structured business-profile data that the platform manages, such as\nthe well-known business-profile knowledge source of an account.\n - KNOWLEDGE_CONFIG_TYPE_CUSTOM_DATA: Free-form text that a user or an integration supplied directly.\n - KNOWLEDGE_CONFIG_TYPE_WEBSITE: Content that the platform collected from a website.\n - KNOWLEDGE_CONFIG_TYPE_FILE: Content that the platform extracted from an uploaded file."
      enum:
      - KNOWLEDGE_CONFIG_TYPE_INVALID
      - KNOWLEDGE_CONFIG_TYPE_BUSINESS_PROFILE
      - KNOWLEDGE_CONFIG_TYPE_CUSTOM_DATA
      - KNOWLEDGE_CONFIG_TYPE_WEBSITE
      - KNOWLEDGE_CONFIG_TYPE_FILE
      type: string
    v2KnowledgeContent:
      description: 'The content to store for a knowledge source on create or update. Exactly

        one variant must be set. The variant determines the config_type of the

        source. On update, the variant must match the config_type of the current

        source. The config_type of a source cannot change after creation.'
      properties:
        file:
          $ref: '#/components/schemas/v2FileContent'
        text:
          $ref: '#/components/schemas/v2TextContent'
      type: object
    v2RemoveKnowledgeRequest:
      description: 'Request to remove a knowledge source from a namespace''s knowledge base,

        either by deleting it or by unlinking it from specific AI Employees.'
      properties:
        accountGroupId:
          description: 'The account group that owns the knowledge source (format:

            "AG-XXXXXXXXXX"). The calling partner must own this account.'
          type: string
        deleteSource:
          $ref: '#/components/schemas/v2DeleteMode'
        knowledgeSourceId:
          description: 'The id of the knowledge source to remove, as UpsertKnowledge or

            ListKnowledge returned it. The source must exist in the namespace.'
          type: string
        partnerId:
          description: 'The partner namespace that owns the knowledge source. Must be the

            calling partner''s own partner id.'
          type: string
        unlink:
          $ref: '#/components/schemas/v2UnlinkMode'
      required:
      - knowledgeSourceId
      type: object
    v2UpsertKnowledgeResponse:
      description: The result of an UpsertKnowledge call.
      properties:
        knowledgeSourceId:
          description: 'The id of the created or updated knowledge source. Keep this id. You

            use it to update, link, or remove the source in subsequent calls. The

            other Knowledge APIs select the source by this id.'
          readOnly: true
          type: string
      type: object
    vendastatypesPagedResponseMetadata:
      properties:
        hasMore:
          title: Whether or not more results exist
          type: boolean
        nextCursor:
          title: A cursor that can be provided to retrieve the next page of results
          type: string
        totalResults:
          format: int64
          title: The total number of results. This is not supported on all paged apis and will be 0 if it is not supported
          type: string
      type: object
    v2FileContent:
      description: 'A file to process into knowledge. Do not send the bytes in this message.

        Supply the upload_handle from the file-upload flow.'
      properties:
        fileName:
          description: 'The original file name to display for the source (for example,

            "handbook.pdf"). At most 255 characters.'
          type: string
        mimeType:
          description: 'The MIME type of the uploaded file (for example, "application/pdf"). At

            most 100 characters.'
          type: string
        uploadHandle:
          description: 'The handle that identifies the uploaded file to ingest, as the

            knowledge file-upload flow issued it. Required when you supply new file

            content.'
          type: string
      required:
      - uploadHandle
      type: object
    protobufAny:
      additionalProperties: {}
      properties:
        '@type':
          type: string
      type: object
    v2GetKnowledgeStatusRequest:
      description: Request to look up the processing status of a single knowledge source.
      properties:
        accountGroupId:
          description: 'The account group that owns the knowledge source (format:

            "AG-XXXXXXXXXX"). The calling partner must own this account.'
          type: string
        knowledgeSourceId:
          description: 'The id of the knowledge source to examine, as UpsertKnowledge or

            ListKnowledge returned it. The source must exist in the namespace.'
          type: string
        partnerId:
          description: 'The partner namespace that owns the knowledge source. Must be the

            calling partner''s own partner id.'
          type: string
      required:
      - knowledgeSourceId
      type: object
    v2GetKnowledgeStatusResponse:
      description: The processing status of the requested knowledge source.
      properties:
        status:
          $ref: '#/components/schemas/v2TrainingStatus'
      type: object
    v2RemoveKnowledgeResponse:
      description: The result of a RemoveKnowledge call.
      type: object
    v2CreateKnowledgeFileUploadRequest:
      description: 'Request to issue a signed URL and handle for uploading a single knowledge

        file directly to storage.'
      properties:
        accountGroupId:
          description: 'The account group whose knowledge base the file is for (format:

            "AG-XXXXXXXXXX"). The calling partner must own this account.'
          type: string
        contentType:
          title: "The MIME type of the file to upload (for example, \"application/pdf\").\nThe signed URL constrains the upload to this type. The PUT must send a\nContent-Type header with the same value. Must be one of the supported\nMIME types:\n  - application/pdf (.pdf)\n  - application/vnd.openxmlformats-officedocument.wordprocessingml.document (.docx)\n  - application/vnd.openxmlformats-officedocument.presentationml.presentation (.pptx)\n  - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet (.xlsx)\n  - application/vnd.ms-excel (.xls)\n  - image/jpeg (.jpg, .jpeg)\n  - image/png (.png)\n  - text/html (.html, .htm)\n  - text/plain (.txt, .text)\n  - text/markdown (.md, .markdown)\n  - text/csv (.csv)\n  - application/json (.json)\n  - application/jsonl (.jsonl)"
          type: string
        fileName:
          description: 'The original file name, including its extension (for example,

            "handbook.pdf"). Used as the display name of the file. At most 255

            characters.'
          type: string
        partnerId:
          description: 'The partner namespace whose knowledge base the file is for. Must be the

            calling partner''s own partner id.'
          type: string
      required:
      - fileName
      - contentType
      type: object
    v2UpsertKnowledgeRequest:
      description: 'Request to create or update a knowledge source and optionally link it to an

        AI Employee.'
      properties:
        accountGroupId:
          description: 'The account group whose knowledge base the source belongs to (format:

            "AG-XXXXXXXXXX"). The calling partner must own this account.'
          type: string
        assistantId:
          description: 'Optional. When set, the API links the knowledge source to this AI

            Employee. The AI Employee can then use the content. Supply the

            assistant id exactly as List Assistants returns it (format:

            "ASSISTANT-XXXX"). The API rejects all other formats, including the

            bare id without the "ASSISTANT-" prefix and internal application ids.

            Links are additive and idempotent. Omit this field to keep the current

            links of the source.'
          type: string
        content:
          $ref: '#/components/schemas/v2KnowledgeContent'
        description:
          description: 'The description of the knowledge source. On update, omit to keep the

            current description. At most 2,000 characters.'
          type: string
        knowledgeSourceId:
          description: 'Optional. The id of the knowledge source to update. Omit this field to

            create a new source. The server generates the id of a new source and

            returns it. When set, the source must already exist in the namespace.'
          type: string
        name:
          description: 'The display name of the knowledge source. Required on create. On update,

            leave empty to keep the current name. At most 500 characters.'
          type: string
        partnerId:
          description: 'The partner namespace whose knowledge base the source belongs to. Must

            be the calling partner''s own partner id.'
          type: string
      type: object
    v2KnowledgeSourceSummary:
      description: 'A summary of one knowledge source in an account''s knowledge base:

        identity, content type, processing status, and timestamps.'
      properties:
        configType:
          $ref: '#/components/schemas/v2KnowledgeConfigType'
        created:
          description: When the knowledge source was created.
          format: date-time
          readOnly: true
          type: string
        fileName:
          description: 'The original file name of the uploaded file. Set only when config_type

            is KNOWLEDGE_CONFIG_TYPE_FILE.'
          readOnly: true
          type: string
        knowledgeSourceId:
          description: 'The unique identifier of the knowledge source in its namespace. Keep

            this id. You use it to update or remove the source later. The other

            Knowledge APIs select the source by this id.'
          readOnly: true
          type: string
        name:
          description: The display name of the knowledge source.
          readOnly: true
          type: string
        status:
          $ref: '#/components/schemas/v2TrainingStatus'
        updated:
          description: When the knowledge source was last updated.
          format: date-time
          readOnly: true
          type: string
      type: object
  securitySchemes:
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          scopes:
            knowledge: Allows the application to manage the knowledge available to AI Employees on your accounts
            knowledge:read: Allows the application view-only access to the knowledge available to AI Employees on your accounts
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
      type: oauth2