SpotDraft V2 Contract Metadata Values API

openapi: 3.2.0
info:
  title: SpotDraft V2 Contract Metadata Values 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 Contract Metadata Values
  description: Read and update contract metadata values for a specific contract. Legacy API paths may still use key-pointer naming.
paths:
  /api/v2/public/contracts/{composite_id}/key_pointers:
    get:
      operationId: v2_public_contracts_key_pointers_retrieve
      description: 'Returns **contract metadata values** for the requested contract.


        Use this when you already have a specific contract id and need the metadata captured on that contract. This is different from the metadata-definition APIs, which list field definitions for a workspace or contract type.


        The underlying API paths still use legacy key-pointer naming for backward compatibility. When the `Enforce-User-Scoping` header is `true`, only metadata values for contracts the specified user may access (based on their permissions) are returned.'
      summary: Get Contract Metadata Values
      parameters:
      - in: path
        name: composite_id
        schema:
          type: string
        description: ID of the Contract. Should be of the form T-123 or H-123. T stands for Template contracts and H stands for Historical contracts.
        required: true
      tags:
      - V2 Contract Metadata Values
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractKeyPointerMinimalListResponse'
          description: Success
      x-tagGroup: Contracts
  /api/v2/public/contracts/{contract_id}/key_pointers/{contract_key_pointer_id}:
    patch:
      operationId: v2_public_contracts_key_pointers_partial_update
      description: Updates the specified contract metadata value. The underlying API path still uses legacy key-pointer naming for backward compatibility.
      summary: Update Contract Metadata Value
      parameters:
      - in: path
        name: contract_id
        schema:
          type: string
        description: ID of the Contract. Should be of the form T-123 or H-123. T stands for Template contracts and H stands for Historical contracts.
        required: true
      - in: path
        name: contract_key_pointer_id
        schema:
          type: string
        description: ID of the contract key pointer value.
        required: true
      tags:
      - V2 Contract Metadata Values
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedContractKeyPointerUpdateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedContractKeyPointerUpdateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedContractKeyPointerUpdateRequest'
      security:
      - ClientId: []
        ClientSecret: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractKeyPointerMinimalResponse'
              examples:
                Example1:
                  value:
                    id: 1
                    value: sample
                    label: Sample Label
                    filed_name: sample_field_name
                    data_type: string
                    format_option:
                      data: sample format option
                  summary: Example 1
          description: Success
      x-tagGroup: Contracts
components:
  schemas:
    ContractKeyPointerMinimalResponse:
      title: ContractKeyPointerMinimalResponse
      type: object
      properties:
        id:
          title: Id
          type: integer
        value:
          title: Value
          description: Value of the key pointer
          anyOf:
          - type: number
          - type: integer
          - type: string
          - type: array
            items: {}
          - type: object
          - type: boolean
        label:
          title: Label
          type: string
        field_name:
          title: Field Name
          type: string
        data_type:
          title: Data Type
          type: string
        format_option:
          title: Format Option
          type: object
      required:
      - id
      - value
      - label
      - field_name
      - data_type
      - format_option
      examples:
      - id: 1
        value: sample
        label: Sample Label
        filed_name: sample_field_name
        data_type: string
        format_option:
          data: sample format option
    PatchedContractKeyPointerUpdateRequest:
      title: ContractKeyPointerUpdateRequest
      type: object
      properties:
        value:
          title: Value
        was_edited_by_user:
          title: Was Edited By User
          default: false
          type: boolean
        value_source_metadata:
          title: Value Source Metadata
          default: []
          type: array
          items:
            title: ValueSourceMetadata
            type: object
            properties:
              id:
                title: Id
                type: string
              value:
                title: Value
              ranked_suggestion:
                title: SuggestionRankingDomainModel
                type: object
                properties:
                  id:
                    title: Id
                    type: integer
                  key_pointer_id:
                    title: Key Pointer Id
                    type: integer
                  suggestion:
                    title: DealPointSuggestionDomainModel
                    type: object
                    properties:
                      id:
                        title: Id
                        type: string
                      historic_contract_id:
                        title: Historic Contract Id
                        type: integer
                      contract_id:
                        title: Contract Id
                        type: integer
                      async_task_id:
                        title: Async Task Id
                        type: string
                      value:
                        title: Value
                        type: string
                      deal_point:
                        title: DealPoint
                        description: Defines the structure of the Dealpoint returned from the pipeline
                        type: object
                        properties:
                          uuid:
                            title: Uuid
                            type: string
                          para_id:
                            title: ParagraphId
                            description: Structure of the paragraph Id returned from the pipeline
                            type: object
                            properties:
                              backend_id:
                                title: Backend Id
                                default: ''
                                type: string
                              uuid:
                                title: Uuid
                                default: ''
                                type: string
                          span:
                            title: Span
                            description: Defines the span for a text in the document
                            type: object
                            properties:
                              id:
                                title: Id
                                type: object
                              text:
                                title: Text
                                default: ''
                                type: string
                              value:
                                title: Value
                                type: object
                              bounding_boxes:
                                title: Bounding Boxes
                                type: array
                                items:
                                  title: BoundingBox
                                  description: Defines the bounding box of a element inside the document.
                                  type: object
                                  properties:
                                    top_left:
                                      title: Coordinates
                                      description: Defines horizontal and vertical position of a point on a page.
                                      type: object
                                      properties:
                                        x:
                                          title: X
                                          type: number
                                        y:
                                          title: Y
                                          type: number
                                      required:
                                      - x
                                      - y
                                    bottom_right:
                                      title: Coordinates
                                      description: Defines horizontal and vertical position of a point on a page.
                                      type: object
                                      properties:
                                        x:
                                          title: X
                                          type: number
                                        y:
                                          title: Y
                                          type: number
                                      required:
                                      - x
                                      - y
                                    page_number:
                                      title: Page Number
                                      type: integer
                                    line_id:
                                      title: Line Id
                                      type: string
                                  required:
                                  - top_left
                                  - bottom_right
                                  - page_number
                              docx_nav_sources:
                                title: Docx Nav Sources
                                type: array
                                items:
                                  title: DocxNavSource
                                  description: Defines a DOCX navigation source for a span.
                                  type: object
                                  properties:
                                    xpath:
                                      title: Xpath
                                      type: string
                                    text:
                                      title: Text
                                      type: string
                                  required:
                                  - text
                              end_index:
                                title: End Index
                                type: integer
                              start_index:
                                title: Start Index
                                default: 0
                                type: integer
                            required:
                            - end_index
                          label:
                            title: Label
                            type: string
                          confidence_score:
                            title: Confidence Score
                            type: number
                          is_removed:
                            title: Is Removed
                            default: false
                            type: boolean
                          source:
                            title: Source
                            type: object
                          standard_text:
                            title: Standard Text
                            type: string
                        required:
                        - uuid
                        - para_id
                        - span
                        - label
                        - confidence_score
                        - source
                      source:
                        title: Source
                        type: string
                    required:
                    - id
                    - async_task_id
                    - value
                    - deal_point
                    - source
                  rank:
                    title: Rank
                    type: integer
                  score:
                    title: Score
                    type: number
                  source:
                    title: Source
                    type: string
                  parsed_value:
                    title: Parsed Value
                required:
                - key_pointer_id
                - suggestion
                - rank
                - score
                - source
              user_selected_span:
                title: SpanBase
                description: Defines essentials for a span definition for a text in the document
                type: object
                properties:
                  id:
                    title: Id
                    type: object
                  text:
                    title: Text
                    default: ''
                    type: string
                  value:
                    title: Value
                    type: object
                  bounding_boxes:
                    title: Bounding Boxes
                    type: array
                    items:
                      title: BoundingBox
                      description: Defines the bounding box of a element inside the document.
                      type: object
                      properties:
                        top_left:
                          title: Coordinates
                          description: Defines horizontal and vertical position of a point on a page.
                          type: object
                          properties:
                            x:
                              title: X
                              type: number
                            y:
                              title: Y
                              type: number
                          required:
                          - x
                          - y
                        bottom_right:
                          title: Coordinates
                          description: Defines horizontal and vertical position of a point on a page.
                          type: object
                          properties:
                            x:
                              title: X
                              type: number
                            y:
                              title: Y
                              type: number
                          required:
                          - x
                          - y
                        page_number:
                          title: Page Number
                          type: integer
                        line_id:
                          title: Line Id
                          type: string
                      required:
                      - top_left
                      - bottom_right
                      - page_number
                  docx_nav_sources:
                    title: Docx Nav Sources
                    type: array
                    items:
                      title: DocxNavSource
                      description: Defines a DOCX navigation source for a span.
                      type: object
                      properties:
                        xpath:
                          title: Xpath
                          type: string
                        text:
                          title: Text
                          type: string
                      required:
                      - text
        source_non_validated_value:
          title: Source Non Validated Value
        source_datatype:
          title: Source Datatype
          type: string
    ContractKeyPointerMinimalListResponse:
      title: ContractKeyPointerMinimalListResponse
      type: array
      items:
        title: ContractKeyPointerMinimalResponse
        type: object
        properties:
          id:
            title: Id
            type: integer
          value:
            title: Value
            description: Value of the key pointer
            anyOf:
            - type: number
            - type: integer
            - type: string
            - type: array
              items: {}
            - type: object
            - type: boolean
          label:
            title: Label
            type: string
          field_name:
            title: Field Name
            type: string
          data_type:
            title: Data Type
            type: string
          format_option:
            title: Format Option
            type: object
        required:
        - id
        - value
        - label
        - field_name
        - data_type
        - format_option
        examples:
        - id: 1
          value: sample
          label: Sample Label
          filed_name: sample_field_name
          data_type: string
          format_option:
            data: sample format option
  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