SpotDraft V2.1 Analytics Query API

openapi: 3.2.0
info:
  title: SpotDraft V2.1 Analytics Query 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 Analytics Query
  description: Read-only analytics SQL execution and related analytics catalog guidance.
paths:
  /api/v2.1/public/analytics/query/:
    post:
      operationId: v2.1_public_analytics_query_create
      description: 'Runs **read-only** analytics SQL in **GoogleSQL** (Google Standard SQL), including for timestamps, dates, and functions. Submit exactly one **`SELECT`** statement (optional **`WITH`** / **`UNION`**). Inserts, updates, deletes, DDL, and multi-statement batches are rejected.


        **Enablement**

        This capability must be enabled for your workspace. If it is not, the API returns **501** with code `SD_PUBLIC_00045`. Contact SpotDraft support to request access.


        **Authentication**

        OAuth 2.0 Bearer JWT in the `Authorization` header (same Public API OAuth flow as other v2.1 endpoints). The authenticated principal must be authorized in the same organizational context as the token.


        **Permission**

        **Insights view** (`INSIGHTS_VIEW`).


        **Contracts scoping**

        By default, the **`Contracts`** table is limited to rows the authenticated user may access. Optional body field **`user_scoped`** or header **`X-Spotdraft-Analytics-User-Scoped`** (`true` / `false`, or `1` / `0`, `yes` / `no`) overrides that. When both are omitted, the default is **`true`** in this environment. **`user_scoped: false`** (or the header equivalent) allows workspace-wide contract rows only for users with the workspace **Admin** role; others receive **403** with `SD_PUBLIC_00044`.


        **Tables and columns**

        Use **bare catalog table names** (e.g. `Contracts`, `Users`) and **snake_case** public column names from the table catalog (e.g. `execution_time`, `workflow_id`). Only allowlisted tables and columns are accepted.


        **Allowlisted tables (quick reference)**


        | Table in SQL | Role |

        |---|---|

        | `Contracts` | Core contract fact table |

        | `Users` | Users / org users |

        | `Workflows_setup` | Workflow definitions (incl. frozen versions) |

        | `Contract_types_setup` | Contract type lookup |

        | `Counterparties_setup` | Counterparty directory |

        | `Approvals_Setup` | Approval steps in workflows |

        | `Entities_setup` | Legal entities |

        | `Signatures_setups` | Signatory configuration per workflow |


        For full column lists, types, and join guidance, see **SpotDraft public analytics table catalog** (also under **External documentation**).


        **Limits (this deployment)**

        - At most **5,000** rows per response; `truncated` is **true** when more rows would have matched.

        - Query job timeout: **60 seconds**.

        - Maximum bytes billed per query job: **500 MB** (500,000,000 bytes).

        - SQL text length limit: **10,000** characters per request.


        **Errors**


        | Code | HTTP | Meaning |

        |---|---:|---|

        | `SD_PUBLIC_00040` | 400 | Not an allowed read-only SELECT, or more than one statement |

        | `SD_PUBLIC_00041` | 400 | References a table outside the allowlisted catalog |

        | `SD_PUBLIC_00042` | 400 | Query could not be parsed or transpiled safely |

        | `SD_PUBLIC_00043` | 502 | Query execution failed |

        | `SD_PUBLIC_00044` | 403 | Workspace-wide contracts requested without workspace Admin role |

        | `SD_PUBLIC_00045` | 501 | Analytics query API not enabled for this workspace |'
      summary: Execute Read-only Analytics SQL (GoogleSQL)
      externalDocs:
        description: Analytics table catalog (columns, types, joins).
        url: '#analytics-query-table-catalog'
      tags:
      - V2.1 Analytics Query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicAnalyticsQueryRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PublicAnalyticsQueryRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PublicAnalyticsQueryRequest'
        required: true
      security:
      - ClientId: []
        ClientSecret: []
      - OAuthBearer: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicAnalyticsQueryResponse'
          description: Query result
        '501':
          description: Feature flag not enabled
      x-tagGroup: Platform
components:
  schemas:
    PublicAnalyticsQueryResponse:
      properties:
        columns:
          description: Column names in result order.
          items:
            type: string
          title: Columns
          type: array
        rows:
          description: Each row is a JSON object keyed by column name. Values are JSON-serializable (e.g. timestamps as ISO 8601 strings).
          items:
            type: object
          title: Rows
          type: array
        row_count:
          description: Number of rows returned after the server row cap is applied.
          title: Row Count
          type: integer
        truncated:
          description: True if more rows existed than were returned (see limits in operation docs).
          title: Truncated
          type: boolean
        execution_ms:
          description: Approximate wall time in milliseconds for transpilation and query execution.
          title: Execution Ms
          type: number
      required:
      - columns
      - rows
      - row_count
      - truncated
      - execution_ms
      title: PublicAnalyticsQueryResponse
      type: object
    PublicAnalyticsQueryRequest:
      description: Body for POST /api/v2.1/public/analytics/query/.
      properties:
        query:
          description: A single GoogleSQL SELECT (optional WITH / UNION). Maximum length 10,000 characters.
          maxLength: 10000
          title: Query
          type: string
        user_scoped:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          description: 'When set, overrides X-Spotdraft-Analytics-User-Scoped. True: restrict Contracts via user_access (default when unset). False: workspace-wide only for users with the workspace Admin role. Non-admin callers cannot widen access by sending `false`.'
          title: User Scoped
      required:
      - query
      title: PublicAnalyticsQueryRequest
      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