SpotDraft V2.1 Sidebar API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Sidebar API
  version: v1
  x-version: v1
  x-logo:
    url: https://cdn.spotdraft.com/assets/logo-black-new.png
    backgroundColor: transparent
    altText: SpotDraft Logo
    href: https://spotdraft.com
  x-favicon: https://cdn.spotdraft.com/assets/favicon.png
  x-footer: © SpotDraft Inc. All rights reserved.
  description: '# SpotDraft Public API


    Welcome to the **SpotDraft Public API**.'
servers:
- url: https://api.eu.spotdraft.com
  description: Europe
- url: https://api.in.spotdraft.com
  description: India
- url: https://api.us.spotdraft.com
  description: United States
- url: https://api.me.spotdraft.com
  description: Middle East
tags:
- name: V2.1 Sidebar
  description: Sidebar APIs for legal questions, contract query workflows, and related AI-assisted experiences.
paths:
  /api/v2.1/public/sidebar/files/:
    post:
      operationId: v2.1_public_sidebar_files_create
      description: 'Upload a file to Sidebar and attach it to a chat, hub, agent, or table.


        - Omit `webhook_url` for a synchronous terminal file result.

        - Provide HTTPS `webhook_url` to receive `202 Accepted` once upload has completed and processing has been scheduled.

        - `upload_source` currently accepts `chat`, `hub`, `assistant`, or `table`. Use `assistant` when you want to attach the file to an agent.'
      summary: Upload Sidebar File
      tags:
      - V2.1 Sidebar
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SidebarFileUploadRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SidebarFileUploadRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SidebarFileUploadRequest'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SidebarFileUploadResponse'
          description: Synchronous upload completed and processing reached a terminal status.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SidebarFileUploadAcceptedResponse'
          description: Accepted for asynchronous processing when `webhook_url` is provided.
        '400':
          description: Validation error while parsing multipart form fields.
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Authentication credentials were not provided.
          description: Unauthorized
        '413':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Uploaded file exceeds the maximum allowed size.
          description: Uploaded file is larger than the configured Sidebar limit.
        '502':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Upstream error
          description: Upstream connection error
        '504':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Upstream timeout
          description: Upstream timeout
      x-tagGroup: Sidebar
  /api/v2.1/public/sidebar/query/:
    post:
      operationId: v2.1_public_sidebar_query_create
      description: 'Ask Sidebar a legal question or continue an existing conversation.


        - Omit `chat_id` to start a new conversation.

        - Provide `chat_id` to continue an existing conversation.

        - Omit `webhook_url` for a synchronous response.

        - Provide HTTPS `webhook_url` to receive `202 Accepted` immediately and get the final result via webhook.


        You can optionally control which sources Sidebar may use and include related files, contracts, tables, or extra context.'
      summary: Run Sidebar Query
      tags:
      - V2.1 Sidebar
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SidebarQueryRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SidebarQueryRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SidebarQueryRequest'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SidebarQueryResponse'
          description: Synchronous Sidebar query result.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SidebarQueryAcceptedResponse'
          description: Accepted for asynchronous processing when `webhook_url` is provided.
        '400':
          description: Validation error while parsing the Sidebar query payload.
        '401':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Authentication credentials were not provided.
          description: Unauthorized
        '502':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Upstream error
          description: Upstream connection error
        '504':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                    description: Error detail.
                required:
                - detail
              examples:
                Example:
                  value:
                    detail: Upstream timeout
          description: Upstream timeout
      x-tagGroup: Sidebar
components:
  schemas:
    SidebarSources:
      type: object
      properties:
        web:
          $ref: '#/components/schemas/SidebarWebSources'
        law:
          $ref: '#/components/schemas/SidebarLawSources'
        clm_connector:
          type: boolean
          default: false
          description: Let Sidebar use your connected SpotDraft contract data.
    SidebarFileContext:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
          description: ID of a file that Sidebar should use.
        file_name:
          type: string
          description: Name of the file, to help you identify it.
        version_number:
          type:
          - integer
          - 'null'
          description: Optional file version to use.
      required:
      - file_id
      - file_name
    SidebarTableContext:
      type: object
      properties:
        table_id:
          type: string
          description: ID of a table that Sidebar should use.
        table_name:
          type: string
          description: Name of the table, to help you identify it.
      required:
      - table_id
      - table_name
    SidebarLawSources:
      type: object
      properties:
        us:
          type: boolean
          default: false
          description: Let Sidebar use US legal materials.
    SidebarFileUploadRequest:
      type: object
      properties:
        file:
          type: string
          format: uri
          description: File to upload to Sidebar.
        upload_source:
          allOf:
          - $ref: '#/components/schemas/UploadSourceEnum'
          description: 'Where the file should be attached. Use `assistant` when attaching it to an agent.


            * `chat` - chat

            * `hub` - hub

            * `assistant` - assistant

            * `table` - table'
        entity_id:
          type: string
          format: uuid
          description: ID of the chat, hub, agent, or table that should receive the file.
        webhook_url:
          type:
          - string
          - 'null'
          format: uri
          pattern: ^https://
          description: Optional HTTPS callback URL. If provided, Sidebar sends the final upload result there instead of keeping this request open.
      required:
      - entity_id
      - file
      - upload_source
    SidebarWebSources:
      type: object
      properties:
        open:
          type: boolean
          default: false
          description: Let Sidebar search the public web.
        indian:
          type: boolean
          default: false
          description: Let Sidebar search Indian legal and government websites.
        eu:
          type: boolean
          default: false
          description: Let Sidebar search EU legal and government websites.
        us:
          type: boolean
          default: false
          description: Let Sidebar search US legal and government websites.
    SidebarQueryResponse:
      type: object
      properties:
        chat_id:
          type: string
          format: uuid
          description: Conversation ID for the created or reused Sidebar chat.
        response:
          type: string
          description: Sidebar's answer.
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SidebarSearchResult'
          description: Sources referenced in the answer.
        error:
          type:
          - string
          - 'null'
          description: Error message if the request failed.
      required:
      - chat_id
      - response
    SidebarSearchResult:
      type: object
      properties:
        title:
          type: string
          description: Title of a source used in the answer.
        url:
          type: string
          format: uri
          description: Link to a source used in the answer.
        source_id:
          type:
          - string
          - 'null'
          description: Optional source identifier.
      required:
      - title
      - url
    SidebarQueryRequest:
      type: object
      properties:
        user_input:
          type: string
          description: Question or instruction to send to Sidebar.
        chat_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Use this to continue an existing Sidebar conversation. Leave it out to start a new one.
        webhook_url:
          type:
          - string
          - 'null'
          format: uri
          pattern: ^https://
          description: Optional HTTPS callback URL. If provided, Sidebar sends the final result there instead of keeping this request open.
        sources:
          allOf:
          - $ref: '#/components/schemas/SidebarSources'
          description: Choose which sources Sidebar is allowed to use.
        deep_research:
          type: boolean
          default: false
          description: Use a deeper research mode. This may take longer.
        files:
          type: array
          items:
            $ref: '#/components/schemas/SidebarFileContext'
          description: Existing files to include as context.
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/SidebarContractContext'
          description: Existing contracts to include as context.
        agent_context:
          type: array
          items:
            type: string
          description: Optional extra notes that Sidebar should consider.
        tables:
          type: array
          items:
            $ref: '#/components/schemas/SidebarTableContext'
          description: Existing tables to include as context.
        agent_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Optional agent to use for this question.
      required:
      - user_input
    UploadSourceEnum:
      enum:
      - chat
      - hub
      - assistant
      - table
      type: string
      description: '* `chat` - chat

        * `hub` - hub

        * `assistant` - assistant

        * `table` - table'
    SidebarFileUploadAcceptedResponse:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
          description: ID of the uploaded file.
        status:
          type: string
          description: Always `accepted` when processing will continue in the background and the terminal file result will be delivered via webhook.
      required:
      - file_id
      - status
    SidebarFileUploadResponse:
      type: object
      properties:
        file_id:
          type: string
          format: uuid
          description: ID of the uploaded file.
        status:
          type: string
          description: Final file status. `created` means the file is ready.
        error:
          type:
          - string
          - 'null'
          description: Error message if processing failed.
      required:
      - file_id
      - status
    SidebarContractContext:
      type: object
      properties:
        contract_id:
          type: string
          description: ID of a contract that Sidebar should use.
        contract_name:
          type: string
          description: Name of the contract, to help you identify it.
      required:
      - contract_id
      - contract_name
    SidebarQueryAcceptedResponse:
      type: object
      properties:
        chat_id:
          type: string
          format: uuid
          description: Conversation ID allocated for the asynchronous request.
        status:
          type: string
          description: Always `accepted` when the result will be delivered later.
      required:
      - chat_id
      - status
  securitySchemes:
    ClickwrapId:
      type: apiKey
      in: header
      name: clickwrap-id
      description: Public clickwrap identifier header.
    ClientId:
      type: apiKey
      name: client-id
      in: header
    ClientSecret:
      type: apiKey
      name: client-secret
      in: header
    NativeIntegrationBasic:
      type: http
      scheme: basic
      description: HTTP Basic auth for supported native integrations. Send base64(client_id:client_secret) in the Authorization header.
    OAuthBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token for workspace user access.
    Origin:
      type: apiKey
      in: header
      name: Origin
      description: Browser origin header used for clickwrap domain validation.
x-logo:
  url: https://cdn.spotdraft.com/assets/logo-black-new.png
  backgroundColor: transparent
  altText: SpotDraft Logo
  href: https://spotdraft.com
x-tagGroups:
- name: Contracts
  tags:
  - V2.1 Contract APIs
  - V2 Contract APIs
  - V1 Contract APIs
  - V2.1 Contract Approvals
  - V2 Contract Approvals
  - V2.1 Contract Activity
  - V2 Contract Activity
  - V2.1 Contract Invitations
  - V2 Contract Invitations
  - V2.1 Contract Metadata Values
  - V2 Contract Metadata Values
  - V2.1 Contract External Metadata
  - V2.1 Contract Notes
  - V2 Contract Notes
  - V2.1 Contract Obligations
  - V2.1 Contract Facets
  - V2.1 Contract Versions
  - V2 Contract Versions
  - V2.1 Recipients
  - V2 Recipients
- name: Clickwrap
  tags:
  - V2.1 Clickwrap
- name: Legal Intake
  tags:
  - V1 Legal Intake
- name: Workflow
  tags:
  - V2.1 Contract Metadata Definitions
  - V2 Contract Metadata Definitions
  - V2.1 Contract Types
  - V2 Contract Types
  - V2.1 Templates
  - V2 Templates
  - V1 Templates
- name: Platform
  tags:
  - V2.1 Users
  - V2 Users
  - V1 Users
  - V2.1 Counterparties
  - V2 Counterparties
  - V2.1 Organizations
  - V2 Organizations
  - V1 Obligation Types
  - V1 Native Integrations
  - V2.1 Workspace Files
  - V2.1 Tasks and Reminders
  - V2 Tasks and Reminders
  - V2.1 Webhooks
  - V1 Webhooks
  - V1 Emails
  - V2.1 Analytics Query
  - V2.1 Workspaces
  - V2.1 Workspace Tags
- name: Sidebar
  tags:
  - V2.1 Sidebar