Caliu Subscription API

openapi: 3.2.0
info:
  title: Caliu Subscription API
  version: 1.0.0
  description: 'API-first notes app. Access your notes programmatically using an API key.


    Create an API key in the app settings, then pass it as `Authorization: Bearer caliu_xxx` header.'
  contact:
    name: Caliu
    url: https://caliuapp.com
servers:
- url: https://api.caliuapp.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Subscription
paths:
  /subscription:
    get:
      tags:
      - Subscription
      summary: Get current entitlement
      description: The signed-in user's Caliu Pro entitlement. `isPro` is the single value clients gate on.
      security:
      - bearerAuth: []
      - cookieAuth: []
      responses:
        '200':
          description: Entitlement
          content:
            application/json:
              schema:
                type: object
                properties:
                  isPro:
                    type: boolean
                  source:
                    type: string
                    enum:
                    - grandfathered
                    - app_store
                    - play_store
                    - stripe
                    - promotional
                    - none
                  expiresAt:
                    type: string
                    nullable: true
                  willRenew:
                    type: boolean
                  plan:
                    type: string
                    nullable: true
                    enum:
                    - subscription
                    - lifetime
                    - null
                    description: 'What backs a paid entitlement: a renewing `subscription` or the one-time `lifetime` purchase. Both unlock the same features. `null` when Pro comes from no store purchase.'
                  noteLimit:
                    type: integer
                    nullable: true
                    description: 'Free note limit for this account (notes outside the trash), or `null` for unlimited. A client-side guard only: note writes and sync are never rejected by the server.'
                  noteCount:
                    type: integer
                    nullable: true
                    description: Notes that count toward `noteLimit`, or `null` when `noteLimit` is. The apps count locally; the MCP server reads this to guard `create_note`.
                required:
                - isPro
                - source
                - expiresAt
                - willRenew
                - plan
                - noteLimit
                - noteCount
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: getSubscription
      x-operation-id-source: derived
  /subscription/reconcile:
    post:
      tags:
      - Subscription
      summary: Re-read this user's entitlement from the store
      description: 'Asks the billing provider for the current entitlement and stores it. Used after sign-in when a purchase was made before an account existed. Takes no body: the account is the authenticated caller.'
      security:
      - bearerAuth: []
      - cookieAuth: []
      responses:
        '200':
          description: Entitlement after reconciliation
          content:
            application/json:
              schema:
                type: object
                properties:
                  reconciled:
                    type: boolean
                  entitlement:
                    type: object
                    properties:
                      isPro:
                        type: boolean
                      source:
                        type: string
                        enum:
                        - grandfathered
                        - app_store
                        - play_store
                        - stripe
                        - promotional
                        - none
                      expiresAt:
                        type: string
                        nullable: true
                      willRenew:
                        type: boolean
                      plan:
                        type: string
                        nullable: true
                        enum:
                        - subscription
                        - lifetime
                        - null
                        description: 'What backs a paid entitlement: a renewing `subscription` or the one-time `lifetime` purchase. Both unlock the same features. `null` when Pro comes from no store purchase.'
                      noteLimit:
                        type: integer
                        nullable: true
                        description: 'Free note limit for this account (notes outside the trash), or `null` for unlimited. A client-side guard only: note writes and sync are never rejected by the server.'
                      noteCount:
                        type: integer
                        nullable: true
                        description: Notes that count toward `noteLimit`, or `null` when `noteLimit` is. The apps count locally; the MCP server reads this to guard `create_note`.
                    required:
                    - isPro
                    - source
                    - expiresAt
                    - willRenew
                    - plan
                    - noteLimit
                    - noteCount
                required:
                - reconciled
                - entitlement
        '401':
          description: Not authenticated
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                - error
      operationId: postSubscriptionReconcile
      x-operation-id-source: derived
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (caliu_xxx) or session token
    cookieAuth:
      type: apiKey
      in: cookie
      name: caliu_session