Granite Drive API

openapi: 3.2.0
info:
  title: Granite Drive API
  version: 1.0.0
  summary: REST API for Granite clients, bots, and integrations.
  description: 'Conventions (apply to every operation; see PLAN.md 3.2 and 3.6):


    - **Base URL** `https://api.granite.md`. All public operations live under `/v1`.

    After Phase 6 ships, `/v1` changes are additive only.

    - **Errors** use RFC 9457 problem details (`application/problem+json`, schema `Problem`).

    The `type` URI is `https://granite.md/problems/`; `code` refines it for programmatic handling.

    Every response carries `X-Request-ID`, also echoed as `request_id` in problems.

    - **Pagination** is cursor based. List operations accept `cursor` and `limit` and return

    `{ "items": [...], "next_cursor": "..." }`. `next_cursor` is absent on the last page.

    Cursors are opaque; clients must not parse or build them.

    - **Idempotency**: non-idempotent `POST` operations accept an `Idempotency-Key` header

    (1-255 printable ASCII). Repeating a request with the same key and body within 24 hours

    returns the original response; the same key with a different body returns `409` with

    code `idempotency_key_reused`.

    - **IDs** are UUIDv7 strings. **Timestamps** are RFC 3339 in UTC.

    - **Authentication**: `Authorization: Bearer ` with a session access token,

    a personal API token (`gr_pat_...`), or an OAuth access token. Scopes are listed per operation.

    - **Rate limits**: each personal API token may make 600 requests a minute. Over the limit

    the API answers `429` with code `token_rate_limited` and a `Retry-After` header (seconds).'
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
- url: https://api.granite.md
  description: Production
- url: http://localhost:8080
  description: Local development
security:
- bearerAuth: []
tags:
- name: Drive
  description: 'Google Drive references (PLAN.md Phase 11). A person connects their Google account

    (only the files they pick are visible to Granite), picks files, and each becomes a

    reference in a vault and a Markdown link in a note. Content is fetched from Google

    when read, converted in memory, and never stored. Everyone who can read the vault can

    read a referenced file through the connection of the person who added it.'
paths:
  /v1/drive/connection:
    get:
      operationId: getDriveConnection
      tags:
      - Drive
      summary: Your Google Drive connection
      responses:
        '200':
          description: Connection state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveConnection'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: disconnectDrive
      tags:
      - Drive
      summary: Disconnect Google Drive
      description: Revokes Granite's access at Google. References stay as links; their content can no longer be read.
      responses:
        '204':
          description: Disconnected (also when there was nothing to disconnect).
        default:
          $ref: '#/components/responses/Error'
  /v1/drive/connect:
    post:
      operationId: startDriveConnect
      tags:
      - Drive
      summary: Start connecting Google Drive
      description: 'Returns Google''s consent page. Google sends the person back to the app''s `/drive/callback`, which finishes with `POST /v1/drive/connect/finish`. Needs Pro (403 `plan_limit_drive`).

        With `client=mobile` (the phone app, which opens the page in the system browser), the

        state starts with `app.`: the web callback then hands `code` and `state` to the phone app

        in a `granite://drive-callback` link instead of finishing itself, and the app finishes.'
      parameters:
      - name: client
        in: query
        required: false
        description: Who finishes the sign-in; `mobile` for the phone app.
        schema:
          type: string
          enum:
          - web
          - mobile
      responses:
        '200':
          description: The page to open.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingRedirect'
        default:
          $ref: '#/components/responses/Error'
  /v1/drive/connect/finish:
    post:
      operationId: finishDriveConnect
      tags:
      - Drive
      summary: Finish connecting Google Drive
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - state
              - code
              additionalProperties: false
              properties:
                state:
                  type: string
                  minLength: 1
                  maxLength: 200
                code:
                  type: string
                  minLength: 1
                  maxLength: 2000
      responses:
        '200':
          description: Connected.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveConnection'
        default:
          $ref: '#/components/responses/Error'
  /v1/drive/picker:
    get:
      operationId: getDrivePicker
      tags:
      - Drive
      summary: A session for Google's file picker
      description: A short-lived access token for your connection, with the browser key and project number the picker needs. 409 `drive_not_connected` or `drive_reconnect`.
      responses:
        '200':
          description: Picker session.
          content:
            application/json:
              schema:
                type: object
                required:
                - access_token
                - expires_at
                - api_key
                - app_id
                properties:
                  access_token:
                    type: string
                  expires_at:
                    type: string
                    format: date-time
                  api_key:
                    type: string
                  app_id:
                    type: string
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/drive-refs:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    get:
      operationId: listDriveRefs
      tags:
      - Drive
      summary: The vault's Drive references
      responses:
        '200':
          description: References, by title.
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/DriveRef'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: addDriveRef
      tags:
      - Drive
      summary: Reference a Drive file you picked
      description: Editors only. Uses your connection; afterwards everyone who can read the vault can read the file through it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - drive_file_id
              additionalProperties: false
              properties:
                drive_file_id:
                  type: string
                  minLength: 1
                  maxLength: 200
      responses:
        '201':
          description: The reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DriveRef'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/drive-refs/{ref_id}:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    - name: ref_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      operationId: deleteDriveRef
      tags:
      - Drive
      summary: Remove a reference
      responses:
        '204':
          description: Removed; links to it in notes stay plain links.
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/drive-refs/{ref_id}/content:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    - name: ref_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: readDriveRef
      tags:
      - Drive
      summary: Read a referenced file's text
      description: 'Fetched from Google now: Docs as Markdown, Sheets as CSV (the first sheet), Slides and

        PDFs as text, text files as they are; at most 10 MB read and 2 MB of text returned.

        404 `drive_no_access`, 409 `drive_reconnect`, 413 `drive_too_large`, 422 `drive_unsupported`.'
      responses:
        '200':
          description: The text.
          content:
            application/json:
              schema:
                type: object
                required:
                - ref
                - text
                - format
                - truncated
                properties:
                  ref:
                    $ref: '#/components/schemas/DriveRef'
                  text:
                    type: string
                  format:
                    type: string
                    enum:
                    - markdown
                    - csv
                    - text
                  truncated:
                    type: boolean
        default:
          $ref: '#/components/responses/Error'
components:
  headers:
    RequestID:
      description: Identifier of this request, for support and log correlation.
      schema:
        type: string
  schemas:
    DriveConnection:
      type: object
      required:
      - available
      - connected
      properties:
        available:
          type: boolean
          description: Google Drive is set up on this server.
        connected:
          type: boolean
        google_account:
          type: string
        state:
          type: string
          enum:
          - ok
          - revoked
          description: '`revoked`: Google no longer accepts the connection; connect again.'
        connected_at:
          type: string
          format: date-time
    BillingRedirect:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
    Problem:
      type: object
      description: RFC 9457 problem details.
      required:
      - type
      - title
      - status
      properties:
        type:
          type: string
          format: uri
          examples:
          - https://granite.md/problems/conflict
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
        code:
          type: string
          description: Machine-readable refinement of `type`, for example `version_conflict`.
        request_id:
          type: string
        errors:
          type: array
          description: Per-field validation errors.
          items:
            $ref: '#/components/schemas/FieldError'
    DriveRef:
      type: object
      required:
      - id
      - drive_file_id
      - title
      - mime_type
      - url
      - state
      - created_at
      properties:
        id:
          type: string
          format: uuid
        drive_file_id:
          type: string
        title:
          type: string
        mime_type:
          type: string
        url:
          type: string
          description: The file in Google Drive (what the note links to).
        icon_url:
          type: string
        modified_at:
          type: string
          format: date-time
        size:
          type: integer
          format: int64
        state:
          type: string
          enum:
          - ok
          - trashed
          - no_access
        created_at:
          type: string
          format: date-time
    FieldError:
      type: object
      required:
      - field
      - detail
      properties:
        field:
          type: string
          description: JSON path of the invalid field, for example `ops[2].path`.
        detail:
          type: string
  parameters:
    VaultID:
      name: vault_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    Error:
      description: Error response.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestID'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Session access token, personal API token, or OAuth access token.