Kagura AI Workspace Plan API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud Workspace Plan API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: workspace-plan
  description: Workspace plan management (self-service)
paths:
  /api/v1/workspaces/{workspace_id}/plan:
    get:
      tags:
      - workspace-plan
      summary: Get Workspace Plan
      description: 'Get workspace plan information.


        Issue #246: Owner-only access (frontend shows in owner-only menu).


        Returns current plan, usage stats, quotas, and upgrade/downgrade options.'
      operationId: get_workspace_plan_api_v1_workspaces__workspace_id__plan_get
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          title: Workspace Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspacePlanInfo'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/plans/available:
    get:
      tags:
      - workspace-plan
      summary: Get Available Plans
      description: 'Get available plan tiers.


        Public information, accessible by any authenticated user.'
      operationId: get_available_plans_api_v1_workspaces_plans_available_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailablePlanInfo'
                title: Response Get Available Plans Api V1 Workspaces Plans Available Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/workspaces/plans/tiers:
    get:
      tags:
      - workspace-plan
      summary: Get Plan Tier Matrix
      description: 'Curated per-tier feature matrix for the Plan page comparison (#1138).


        Single source of truth = ``config/plan_tiers.py`` (env-overridable). Price is

        omitted by design — pricing lives in www / the payment service. Returns the

        tiers in upgrade order (free → basic → pro). Public reference data; accessible

        by any authenticated session user (the Plan page itself is owner-gated).


        Each row also carries ``feature_enforcement`` (#1648): the registry''s

        per-feature runtime mode, so a client can tell a real gate from a plan-page

        label instead of assuming every feature name is enforced.


        Path note: the ``/workspaces/plans/...`` two-segment shape (mirroring

        ``/workspaces/plans/available``) is deliberate — a one-segment

        ``/workspaces/plan-tiers`` would be shadowed by the earlier-registered

        ``GET /workspaces/{workspace_id}`` route and 422 on the UUID parse.'
      operationId: get_plan_tier_matrix_api_v1_workspaces_plans_tiers_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlanTierFeature'
                title: Response Get Plan Tier Matrix Api V1 Workspaces Plans Tiers Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PlanTierFeature:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        max_contexts:
          type: integer
          title: Max Contexts
        max_members:
          type: integer
          title: Max Members
        owned_workspaces:
          type: integer
          title: Owned Workspaces
        memory_limit:
          type: integer
          title: Memory Limit
        memories_per_day:
          type: integer
          title: Memories Per Day
        storage_limit_bytes:
          type: integer
          title: Storage Limit Bytes
        mcp_calls_per_day:
          type: integer
          title: Mcp Calls Per Day
        rest_calls_per_day:
          type: integer
          title: Rest Calls Per Day
        public_calls_per_day:
          type: integer
          title: Public Calls Per Day
        max_resource_tokens:
          type: integer
          title: Max Resource Tokens
        max_connectors:
          type: integer
          title: Max Connectors
        max_content_chunk_contexts:
          type: integer
          title: Max Content Chunk Contexts
        max_llm_selector_contexts:
          type: integer
          title: Max Llm Selector Contexts
        analysis_runs_per_day:
          type: integer
          title: Analysis Runs Per Day
        sleep_enabled_contexts_limit:
          type: integer
          title: Sleep Enabled Contexts Limit
        reranking:
          type: boolean
          title: Reranking
        managed_embeddings:
          type: boolean
          title: Managed Embeddings
        managed_llm:
          type: boolean
          title: Managed Llm
        secret_store:
          type: boolean
          title: Secret Store
        shared_contexts:
          type: boolean
          title: Shared Contexts
        team_invitations:
          type: boolean
          title: Team Invitations
        resources:
          type: boolean
          title: Resources
        connectors:
          type: boolean
          title: Connectors
        public_contexts:
          type: boolean
          title: Public Contexts
        content_chunks:
          type: boolean
          title: Content Chunks
        llm_selector:
          type: boolean
          title: Llm Selector
        operation_history:
          type: boolean
          title: Operation History
          default: false
        feature_enforcement:
          additionalProperties:
            type: string
          type: object
          title: Feature Enforcement
      type: object
      required:
      - name
      - display_name
      - max_contexts
      - max_members
      - owned_workspaces
      - memory_limit
      - memories_per_day
      - storage_limit_bytes
      - mcp_calls_per_day
      - rest_calls_per_day
      - public_calls_per_day
      - max_resource_tokens
      - max_connectors
      - max_content_chunk_contexts
      - max_llm_selector_contexts
      - analysis_runs_per_day
      - sleep_enabled_contexts_limit
      - reranking
      - managed_embeddings
      - managed_llm
      - secret_store
      - shared_contexts
      - team_invitations
      - resources
      - connectors
      - public_contexts
      - content_chunks
      - llm_selector
      - feature_enforcement
      title: PlanTierFeature
      description: 'One tier''s curated feature/limit values for the comparison matrix (#1138).


        Single source of truth = ``config/plan_tiers.py`` (env-overridable). Price is

        intentionally omitted — pricing lives in www / the payment service; this

        surface is feature *limits* only, so the OSS Plan page never fabricates an

        amount (consistent with #1141 / #1096). Numeric fields use ``0`` for "not

        available on this tier"; the frontend renders that as ✗.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WorkspacePlanQuotas:
      properties:
        memory_limit:
          type: integer
          title: Memory Limit
        max_contexts:
          type: integer
          title: Max Contexts
        max_resource_tokens:
          type: integer
          title: Max Resource Tokens
        max_quota_capacity:
          type: integer
          title: Max Quota Capacity
        mcp_calls_per_day:
          type: integer
          title: Mcp Calls Per Day
        mcp_calls_per_week:
          type: integer
          title: Mcp Calls Per Week
        rest_calls_per_day:
          type: integer
          title: Rest Calls Per Day
        public_calls_per_day:
          type: integer
          title: Public Calls Per Day
      type: object
      required:
      - memory_limit
      - max_contexts
      - max_resource_tokens
      - max_quota_capacity
      - mcp_calls_per_day
      - mcp_calls_per_week
      - rest_calls_per_day
      - public_calls_per_day
      title: WorkspacePlanQuotas
      description: 'Effective quotas of one workspace, as ``GET /workspaces/{id}/plan`` returns them.


        Typed rather than a bare ``dict`` because the frontend reads named keys off

        this payload: the token screens take "used / max" and the quota-capacity

        line from ``max_resource_tokens`` / ``max_quota_capacity`` (#1560). A rename

        here must fail pyright at the construction site, not silently degrade the UI

        to its "cap unknown" fallback.'
    WorkspacePlanInfo:
      properties:
        workspace_id:
          type: string
          title: Workspace Id
        workspace_name:
          type: string
          title: Workspace Name
        current_plan:
          type: string
          title: Current Plan
        plan_display_name:
          type: string
          title: Plan Display Name
        usage:
          additionalProperties: true
          type: object
          title: Usage
        quotas:
          $ref: '#/components/schemas/WorkspacePlanQuotas'
        can_upgrade:
          type: boolean
          title: Can Upgrade
        can_downgrade:
          type: boolean
          title: Can Downgrade
        suspended:
          items:
            type: string
          type: array
          title: Suspended
      type: object
      required:
      - workspace_id
      - workspace_name
      - current_plan
      - plan_display_name
      - usage
      - quotas
      - can_upgrade
      - can_downgrade
      title: WorkspacePlanInfo
      description: Workspace plan information with usage stats.
    AvailablePlanInfo:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        quotas:
          additionalProperties: true
          type: object
          title: Quotas
        features:
          items:
            type: string
          type: array
          title: Features
      type: object
      required:
      - name
      - display_name
      - quotas
      - features
      title: AvailablePlanInfo
      description: Available plan tier information.