Granite Vaults API

openapi: 3.2.0
info:
  title: Granite Vaults 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: Vaults
  description: Vaults (folders of notes that sync).
paths:
  /v1/vaults:
    get:
      operationId: listVaults
      tags:
      - Vaults
      summary: List vaults
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - name: trash
        in: query
        required: false
        description: List deleted vaults that can still be restored instead of active ones.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: A page of vaults.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultList'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createVault
      tags:
      - Vaults
      summary: Create a vault
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultCreate'
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    get:
      operationId: getVault
      tags:
      - Vaults
      summary: Get a vault
      responses:
        '200':
          description: The vault.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateVault
      tags:
      - Vaults
      summary: Rename a vault
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VaultUpdate'
      responses:
        '200':
          description: The updated vault.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: deleteVault
      tags:
      - Vaults
      summary: Move a vault to the trash
      description: The vault can be restored for 30 days (`purge_after`), then it is deleted permanently.
      responses:
        '200':
          description: The deleted vault.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/export:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    get:
      operationId: exportVault
      tags:
      - Vaults
      summary: Download a vault as a zip of plain files
      description: Every file you can read, at its path, exactly as synced (PLAN.md 5, Portability). Needs the vault owner's plan to include exports (Pro and Business; `plan_limit_data_export` otherwise).
      responses:
        '200':
          description: The archive.
          headers:
            Content-Disposition:
              schema:
                type: string
          content:
            application/zip:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/restore:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    post:
      operationId: restoreVault
      tags:
      - Vaults
      summary: Restore a vault from the trash
      responses:
        '200':
          description: The restored vault.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Vault'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/grants:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    get:
      operationId: listGrants
      tags:
      - Vaults
      summary: Who a shared vault is shared with
      description: Vault admins.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrantList'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createGrant
      tags:
      - Vaults
      summary: Share a vault, a folder, or a note
      description: Vault admins of workspace vaults (inside a restricted folder, those who administer it; never inside a private folder). With `folder`, access applies to that folder or note only. Granting the same person or group and folder again changes the access. Guests can only read and comment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GrantCreate'
      responses:
        '201':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Grant'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/grants/{grant_id}:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    - name: grant_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      operationId: deleteGrant
      tags:
      - Vaults
      summary: Stop sharing
      description: Vault admins. Applies from the next request.
      responses:
        '204':
          description: Done.
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/restrictions:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    get:
      operationId: listRestrictions
      tags:
      - Vaults
      summary: Restricted and private folders
      description: Workspace owners and admins see all of them (private folders by name only); others see those they can open.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestrictionList'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: createRestriction
      tags:
      - Vaults
      summary: Restrict a folder or note, or make a folder private
      description: 'Workspace vaults (Business). Restricted (`private` false; owners and admins): only grants made at or below the path count inside it, so it opens only to the teams and people it is then shared with (and owners and admins). Private (`private` true; any member who can edit it): only the caller can open it, workspace owners and admins included; they still see that it exists and can lift it. Restricting the same path again changes its kind.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestrictionCreate'
      responses:
        '201':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Restriction'
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/restrictions/{restriction_id}:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    - name: restriction_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    delete:
      operationId: deleteRestriction
      tags:
      - Vaults
      summary: Lift a restriction or a folder's privacy
      description: A private folder's member, or workspace owners and admins. Applies from the next request.
      responses:
        '204':
          description: Done.
        default:
          $ref: '#/components/responses/Error'
  /v1/vaults/{vault_id}/access:
    parameters:
    - $ref: '#/components/parameters/VaultID'
    get:
      operationId: getPathAccess
      tags:
      - Vaults
      summary: Who can open a folder or note
      description: Anyone who can read the path. Says whether it is private or restricted and what the caller may change.
      parameters:
      - name: path
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 1024
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PathAccess'
        default:
          $ref: '#/components/responses/Error'
components:
  headers:
    RequestID:
      description: Identifier of this request, for support and log correlation.
      schema:
        type: string
  schemas:
    GrantCreate:
      type: object
      required:
      - principal_type
      - principal_id
      - access
      properties:
        principal_type:
          type: string
          enum:
          - user
          - group
        principal_id:
          type: string
          format: uuid
        access:
          type: string
          enum:
          - read
          - comment
          - write
          - admin
        folder:
          type: string
          maxLength: 1024
    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
    VaultList:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Vault'
        next_cursor:
          type: string
    Restriction:
      type: object
      required:
      - id
      - folder
      - private
      - created_at
      properties:
        id:
          type: string
          format: uuid
        folder:
          type: string
          description: The restricted folder or note.
        private:
          type: boolean
        private_to:
          type: string
          format: uuid
          description: The member a private folder belongs to.
        created_at:
          type: string
          format: date-time
    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'
    Grant:
      type: object
      required:
      - id
      - principal_type
      - principal_id
      - access
      - folder
      - created_at
      properties:
        id:
          type: string
          format: uuid
        principal_type:
          type: string
          enum:
          - user
          - group
        principal_id:
          type: string
          format: uuid
        access:
          type: string
          enum:
          - read
          - comment
          - write
          - admin
        folder:
          type: string
          description: The folder the grant is for; "" for the whole vault.
        created_at:
          type: string
          format: date-time
    VaultUpdate:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
    RestrictionCreate:
      type: object
      required:
      - path
      - private
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 1024
        private:
          type: boolean
    Vault:
      type: object
      required:
      - id
      - name
      - created_at
      - updated_at
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        workspace_id:
          type: string
          format: uuid
          description: The workspace that owns a shared vault (absent for personal vaults).
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          description: Set when the vault is in the trash.
        purge_after:
          type: string
          format: date-time
          description: When a vault in the trash is deleted permanently.
    VaultCreate:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        workspace_id:
          type: string
          format: uuid
          description: Create a shared vault in this workspace (members and above) instead of a personal one.
    GrantList:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Grant'
    PathAccess:
      type: object
      required:
      - path
      - private
      - restricted
      - restricted_at
      - can_manage
      - can_make_private
      - openers
      properties:
        path:
          type: string
        private:
          type: boolean
          description: Inside a private folder (only its member can open it).
        restricted:
          type: boolean
          description: Inside a folder limited to its own grants.
        restricted_at:
          type: string
          description: The innermost restricted or private folder covering the path ("" when none).
        restriction:
          $ref: '#/components/schemas/Restriction'
        can_manage:
          type: boolean
          description: The caller may restrict the path and choose who opens it (workspace owners and admins).
        can_make_private:
          type: boolean
          description: The caller may make it private, or lift its privacy.
        openers:
          type: array
          items:
            $ref: '#/components/schemas/Opener'
    RestrictionList:
      type: object
      required:
      - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Restriction'
    Opener:
      type: object
      required:
      - kind
      - access
      - folder
      properties:
        kind:
          type: string
          enum:
          - owner
          - user
          - group
          - admin
          description: The personal vault's owner, a member, a team (group), or a workspace owner or admin.
        id:
          type: string
          format: uuid
        name:
          type: string
        email:
          type: string
        access:
          type: string
          enum:
          - read
          - comment
          - write
          - admin
        folder:
          type: string
          description: Where the grant was made; "" for the whole vault.
        members:
          type: integer
          format: int64
          description: For teams.
        grant_id:
          type: string
          format: uuid
  parameters:
    VaultID:
      name: vault_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
    Limit:
      name: limit
      in: query
      required: false
      description: Maximum items to return.
      schema:
        type: integer
        format: int32
        minimum: 1
        maximum: 200
        default: 50
    Cursor:
      name: cursor
      in: query
      required: false
      description: Opaque cursor from a previous page's `next_cursor`.
      schema:
        type: string
        maxLength: 512
  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.