Fundamental Research Labs Authentication API

openapi: 3.2.0
info:
  title: Shortcut Authentication API
  version: 1.0.0
  description: 'Shortcut API lets teams automate spreadsheet workflows and export organization usage data programmatically.


    ## Getting Started


    ### Create an API key


    1. Go to shortcut.ai

    2. Navigate to **Settings → API Keys**

    3. Create a new API key


    External callers use an API key in the `Authorization` header as a Bearer token:

    `Authorization: Bearer sc-xxx`


    Authenticated Shortcut applications can call spreadsheet automation routes with

    the user''s Shortcut session or access token for run, upload, status, download,

    skills, and cancel operations. Non-browser applications send the JWT as a

    bearer token; Shortcut web applications may use the same JWT through the

    `shortcut_access_token` cookie in a credentialed request from a trusted

    Shortcut origin. `/verify` and webhooks require API key authentication because

    they depend on API key and webhook-secret state.


    Registered integrations can also use authorization-code OAuth with S256 PKCE

    and client authentication. The user approves `api:access`; the integration

    sends its OAuth access token as a Bearer token on spreadsheet routes. This

    preserves the user''s ownership, subscription, and credit checks. OAuth does not

    support API-key verification, webhooks, or organization usage export.


    ### Spreadsheet automation workflow


    1. **Verify your API key**: `GET /api/spreadsheets/verify`

    2. **Submit a job**: `POST /api/spreadsheets` with a prompt

    3. **Check status**: `GET /api/spreadsheets/:runId` (poll until completed, failed, or error)

    4. **Download result**: `GET /api/spreadsheets/:runId/download`


    ### Usage export workflow


    1. Open **Usage Metrics** in Shortcut.

    2. Copy the prefilled command from **Programmatic export**.

    3. Use the Usage API reference to customize date range, format, or grouping.


    ### Spreadsheet automation limits


    - Maximum 2000 concurrent jobs per API key

    - Job timeout: 30 minutes (configurable up to 120 minutes)'
tags:
- name: Authentication
  description: API key authentication and verification
paths:
  /api/spreadsheets/verify:
    get:
      summary: Verify API Credentials
      tags:
      - Authentication
      description: Verifies an API key or OAuth access token. Only API-key responses include a webhook secret.
      security:
      - apiKey: []
      - shortcutOAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Request success status
                    enum:
                    - true
                  message:
                    type: string
                    description: Success message
                  webhookSecret:
                    type: string
                    description: 'Returned only for API keys: HMAC-SHA256 secret for verifying the X-Shortcut-Signature header on incoming webhooks.'
                required:
                - success
                - message
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Request success status
                    enum:
                    - false
                  error:
                    type: string
                    description: Error type
                  message:
                    type: string
                    description: Error message
                required:
                - success
                - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Request success status
                    enum:
                    - false
                  error:
                    type: string
                    description: Error type
                required:
                - success
                - error
                additionalProperties: false
      operationId: getApiSpreadsheetsVerify
      x-operation-id-source: derived
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key in Bearer token format: `Authorization: Bearer sc-xxx`'
    shortcutOAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth access token
      description: Delegated OAuth access token with api:access scope. Existing user permissions and billing apply.
    shortcutSession:
      type: http
      scheme: bearer
      bearerFormat: Shortcut Session
      description: First-party Shortcut application session or access token sent as an explicit Bearer token.
    shortcutCookie:
      type: apiKey
      in: cookie
      name: shortcut_access_token
      description: Shortcut web session cookie for credentialed fetch requests. Missing or untrusted Origin headers are rejected.
x-provenance:
  method: harvested
  publisher: Fundamental Research Labs
  source: https://api.shortcut.ai/api/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)