Kagura AI API Keys API

openapi: 3.2.0
info:
  title: Kagura Memory Cloud API Keys API
  description: Universal AI Memory Platform - Remote MCP Server + Web Management
  version: 0.158.1
tags:
- name: API Keys
  description: MCP API key management
paths:
  /api/v1/config/api-keys:
    get:
      tags:
      - API Keys
      summary: List Api Keys
      description: 'List API keys for the current user.


        Issue #246: Returns all user''s API keys (no context filtering).'
      operationId: list_api_keys_api_v1_config_api_keys_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/APIKeyResponse'
                title: Response List Api Keys Api V1 Config Api Keys Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - API Keys
      summary: Create Api Key
      description: 'Create a new API key for the current user.


        Issue #246: Creates API key with context_id=None (no auto-assignment).

        Issue #1752: the owner is emailed a security notice once the key is

        committed (the key''s name only, never its value).'
      operationId: create_api_key_api_v1_config_api_keys_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKeyCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/api-keys/{key_id}:
    delete:
      tags:
      - API Keys
      summary: Delete Api Key
      description: 'Permanently delete an API key.


        Issue #112: Delete by ID directly to avoid ambiguity with duplicate names across contexts.


        WARNING: Hard delete. Use POST /{key_id}/revoke for soft delete.'
      operationId: delete_api_key_api_v1_config_api_keys__key_id__delete
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          description: Public id of the API key (`akey_` + 22 base62 characters).
          examples:
          - akey_0000000000000000000000
          title: Key Id
        description: Public id of the API key (`akey_` + 22 base62 characters).
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - API Keys
      summary: Update Api Key
      description: 'Set or clear the key''s MCP default context (#2129).


        The only field this route changes. A context-scoped MCP tool called with

        this key and without ``context_id`` runs in the default (``?context=``

        on the URL wins). The context must be readable by the key''s owner now,

        within the key''s workspace scope; otherwise 404 ``Context not found``

        (the same answer for a context that does not exist). Public-bound and

        agent-bound keys cannot carry one (422): an agent key''s default is its

        agent''s default binding.


        Raises:

        NotFoundException: The key is not the caller''s, or the context is not

        readable (404).

        BadRequestError: The key is revoked (400).

        ValidationError: The key is public-bound, agent-bound or a connector''s

        shared key (422).'
      operationId: update_api_key_api_v1_config_api_keys__key_id__patch
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          description: Public id of the API key (`akey_` + 22 base62 characters).
          examples:
          - akey_0000000000000000000000
          title: Key Id
        description: Public id of the API key (`akey_` + 22 base62 characters).
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/APIKeyUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/api-keys/{key_id}/revoke:
    post:
      tags:
      - API Keys
      summary: Revoke Api Key
      description: 'Revoke an API key (soft delete, preserves audit trail).


        Issue #112: Revoke by ID directly to avoid ambiguity with duplicate names.'
      operationId: revoke_api_key_api_v1_config_api_keys__key_id__revoke_post
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          description: Public id of the API key (`akey_` + 22 base62 characters).
          examples:
          - akey_0000000000000000000000
          title: Key Id
        description: Public id of the API key (`akey_` + 22 base62 characters).
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/api-keys/{key_id}/regenerate:
    post:
      tags:
      - API Keys
      summary: Regenerate Api Key
      description: 'Regenerate an API key (revokes old key, creates new one with same name).


        Issue #169: Secret regeneration feature. Issue #1752: the owner is emailed

        a security notice after the commit.


        WARNING: This immediately invalidates the old key. Update all applications.'
      operationId: regenerate_api_key_api_v1_config_api_keys__key_id__regenerate_post
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          description: Public id of the API key (`akey_` + 22 base62 characters).
          examples:
          - akey_0000000000000000000000
          title: Key Id
        description: Public id of the API key (`akey_` + 22 base62 characters).
      - 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/APIKeyCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/config/api-keys/{key_id}/stats:
    get:
      tags:
      - API Keys
      summary: Get Api Key Stats
      description: Get API key usage statistics.
      operationId: get_api_key_stats_api_v1_config_api_keys__key_id__stats_get
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          pattern: ^akey_[0-9A-Za-z]{22}$
          description: Public id of the API key (`akey_` + 22 base62 characters).
          examples:
          - akey_0000000000000000000000
          title: Key Id
        description: Public id of the API key (`akey_` + 22 base62 characters).
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIKeyStats'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    APIKeyStats:
      properties:
        total_requests:
          type: integer
          minimum: 0.0
          title: Total Requests
          description: Total requests in period
        daily_stats:
          items:
            $ref: '#/components/schemas/DailyStats'
          type: array
          title: Daily Stats
          description: Daily breakdown
        period_start:
          type: string
          title: Period Start
          description: Start date of statistics period
        period_end:
          type: string
          title: Period End
          description: End date of statistics period
      type: object
      required:
      - total_requests
      - daily_stats
      - period_start
      - period_end
      title: APIKeyStats
      description: API key usage statistics.
    DailyStats:
      properties:
        date:
          type: string
          title: Date
          description: Date in ISO format (YYYY-MM-DD)
        count:
          type: integer
          minimum: 0.0
          title: Count
          description: Number of requests on this date
      type: object
      required:
      - date
      - count
      title: DailyStats
      description: Daily usage statistics.
    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
    APIKeyCreate:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: Friendly name for the API key
        expires_days:
          anyOf:
          - type: integer
            maximum: 3650.0
            minimum: 0.0
          - type: 'null'
          title: Expires Days
          description: Expiration in days (1-3650). Omit for the server default (365 days); 0 opts in to a key that never expires.
        default_context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Default Context Id
          description: 'MCP default context of the key: a context-scoped tool called without context_id runs in it (?context= on the URL wins). Omit for none.'
      type: object
      required:
      - name
      title: APIKeyCreate
      description: Request model for creating an API key.
    APIKeyCreateResponse:
      properties:
        id:
          title: Id
          description: Public id of the key (`akey_` + 22 base62 characters)
        key_prefix:
          title: Key Prefix
          description: First 16 characters of key (for display)
        name:
          title: Name
          description: Friendly name
        user_id:
          title: User Id
          description: Owner user ID
        created_at:
          title: Created At
          description: Creation timestamp
        last_used_at:
          title: Last Used At
          description: Last usage timestamp
        revoked_at:
          title: Revoked At
          description: Revocation timestamp
        expires_at:
          title: Expires At
          description: Expiration timestamp
        status:
          title: Status
          description: Current status
        default_context_id:
          title: Default Context Id
          description: The key's MCP default context (#2129); null when none.
        default_context_name:
          title: Default Context Name
          description: Name of the default context; null when none is set or the context is no longer readable by the key's owner.
        connector_id:
          title: Connector Id
          description: The connector this key is the shared write key of (#1952); null for an ordinary key. Classify connector keys by this, not by the name (#2299).
        api_key:
          title: Api Key
          description: Plaintext API key (ONLY shown once - must be saved by client)
      type: object
      required:
      - id
      - key_prefix
      - name
      - user_id
      - created_at
      - status
      - api_key
      title: APIKeyCreateResponse
      description: Response model for API key creation (includes plaintext key).
    APIKeyUpdate:
      properties:
        default_context_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Default Context Id
          description: The key's MCP default context; null clears it.
      type: object
      required:
      - default_context_id
      title: APIKeyUpdate
      description: Request model for ``PATCH /config/api-keys/{key_id}`` (#2129).
    APIKeyResponse:
      properties:
        id:
          title: Id
          description: Public id of the key (`akey_` + 22 base62 characters)
        key_prefix:
          title: Key Prefix
          description: First 16 characters of key (for display)
        name:
          title: Name
          description: Friendly name
        user_id:
          title: User Id
          description: Owner user ID
        created_at:
          title: Created At
          description: Creation timestamp
        last_used_at:
          title: Last Used At
          description: Last usage timestamp
        revoked_at:
          title: Revoked At
          description: Revocation timestamp
        expires_at:
          title: Expires At
          description: Expiration timestamp
        status:
          title: Status
          description: Current status
        default_context_id:
          title: Default Context Id
          description: The key's MCP default context (#2129); null when none.
        default_context_name:
          title: Default Context Name
          description: Name of the default context; null when none is set or the context is no longer readable by the key's owner.
        connector_id:
          title: Connector Id
          description: The connector this key is the shared write key of (#1952); null for an ordinary key. Classify connector keys by this, not by the name (#2299).
      type: object
      required:
      - id
      - key_prefix
      - name
      - user_id
      - created_at
      - status
      title: APIKeyResponse
      description: Response model for API key metadata.