SpotDraft V2.1 Workspace Tags API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Workspace Tags 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 Workspace Tags
  description: Create and manage workspace tags used to categorize and filter contracts.
paths:
  /api/v2.1/public/workspace/tags/:
    post:
      operationId: v2.1_public_workspace_tags_create
      description: 'Bulk-create one or more workspace tags.


        Tags are used to categorize, identify, and filter contracts within a workspace.

        Use this endpoint to create multiple tags in a single request before assigning them to contracts.


        **Required fields per tag:** `name`


        **Optional fields per tag:**

        - `colour_code` — hex colour string (e.g. `"#FF5733"`); defaults to empty string

        - `tag_entity_type` — `"Contract"` (default) or `"Clause"`


        **Responses:**

        - `201 Created` — all tags were created successfully; returns the created tag objects with their IDs

        - `400 Bad Request` — one or more tags already exist in the workspace, or the request body is invalid'
      summary: Bulk Create Workspace Tags
      tags:
      - V2.1 Workspace Tags
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicBulkTagCreateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicBulkTagCreateRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicBulkTagCreateRequest'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      - OAuthBearer: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicBulkTagCreateResponse'
          description: Tags created successfully.
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                  code:
                    type: string
                  status_code:
                    type: integer
                  message:
                    type: string
          description: Tag already exists in the workspace, or the request body is invalid. Malformed bodies are returned as field-keyed validation errors (via the global exception handler); duplicate tags use the standard SpotDraft error object with detail, code, status_code, and message.
        '401':
          description: Unauthorized — invalid or missing API credentials.
      x-tagGroup: Platform
components:
  schemas:
    PublicBulkTagCreateRequest:
      description: Request body for bulk tag creation.
      examples:
      - tags:
        - colour_code: '#FF5733'
          name: NDA
        - name: MSA
        - colour_code: '#3498DB'
          name: SOW
          tag_entity_type: Contract
      properties:
        tags:
          description: List of tags to create. Each tag requires at minimum a 'name' field.
          items:
            $ref: '#/components/schemas/PublicTagCreateRequest'
          minItems: 1
          title: Tags
          type: array
      required:
      - tags
      title: PublicBulkTagCreateRequest
      type: object
    TagEntityType:
      description: Enum type to indicate type of the entity for which the tags correspond to
      enum:
      - Contract
      - Clause
      title: TagEntityType
      type: string
    PublicTagResponse:
      description: Response model for a created tag.
      examples:
      - colour_code: '#FF5733'
        id: 42
        name: NDA
        tag_entity_type: Contract
        workspace_id: 101
      properties:
        id:
          description: Unique identifier of the tag
          title: Id
          type: integer
        name:
          description: Name of the tag
          title: Name
          type: string
        workspace_id:
          description: ID of the workspace the tag belongs to
          title: Workspace Id
          type: integer
        colour_code:
          description: Hex colour code for the tag
          title: Colour Code
          type: string
        tag_entity_type:
          $ref: '#/components/schemas/TagEntityType'
          description: Entity type the tag applies to
      required:
      - id
      - name
      - workspace_id
      - colour_code
      - tag_entity_type
      title: PublicTagResponse
      type: object
    PublicBulkTagCreateResponse:
      description: Response body for bulk tag creation.
      examples:
      - tags:
        - colour_code: '#FF5733'
          id: 42
          name: NDA
          tag_entity_type: Contract
          workspace_id: 101
      properties:
        tags:
          description: List of successfully created tags
          items:
            $ref: '#/components/schemas/PublicTagResponse'
          title: Tags
          type: array
      required:
      - tags
      title: PublicBulkTagCreateResponse
      type: object
    PublicTagCreateRequest:
      description: Request model for a single tag to be created.
      examples:
      - colour_code: '#FF5733'
        name: NDA
        tag_entity_type: Contract
      properties:
        name:
          description: Name of the tag to create (1–100 characters, not empty or whitespace-only).
          maxLength: 100
          minLength: 1
          title: Name
          type: string
        colour_code:
          default: ''
          description: Colour code for the tag (e.g. '#FF5733'); up to 10 characters. Defaults to an empty string.
          maxLength: 10
          title: Colour Code
          type: string
        tag_entity_type:
          $ref: '#/components/schemas/TagEntityType'
          default: Contract
          description: Entity type the tag applies to. One of 'Contract' or 'Clause'. Defaults to 'Contract'.
      required:
      - name
      title: PublicTagCreateRequest
      type: object
  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