CoreStory API Key Management API

openapi: 3.2.0
info:
  title: Crowdbotics API Documentation API Key Management API
  description: '# CoreStory API Overview


    The CoreStory API provides programmatic access to structured insights derived from software source code.'
  version: 1.26.2
servers:
- url: /
  description: Current server
security:
- BearerAuth: []
tags:
- name: API Key Management
paths:
  /api/api-keys:
    post:
      tags:
      - API Key Management
      summary: Create a new API key
      description: 'Create a new API key for programmatic access.


        The key is returned ONLY ONCE in the response. Save it securely!


        API keys inherit your current permissions in the organization.

        When your permissions change in Clerk, the API key automatically

        reflects those changes.


        **Scope Types:**

        - `user`: Full access based on your organization permissions

        - `project`: Access limited to a specific project

        - `organization`: Machine-to-machine (M2M) key not tied to a specific user'
      operationId: create_api_key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    get:
      tags:
      - API Key Management
      summary: List all API keys
      description: List all API keys for the current user in the current organization.
      operationId: list_api_keys
      parameters:
      - name: include_revoked
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Include Revoked
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyListResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/api-keys/refresh:
    post:
      tags:
      - API Key Management
      summary: Refresh (rotate) an API key
      description: 'Refresh an existing API key by revoking the current one and generating a new one.


        This endpoint finds the active key matching the specified scope, revokes it,

        and creates a new key with the same name and description.


        The new key is returned ONLY ONCE in the response. Save it securely!


        **Use Cases:**

        - Key rotation for security compliance

        - Replacing a potentially compromised key

        - Refreshing an expiring key'
      operationId: refresh_api_key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyRefreshRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyCreateResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/api-keys/{key_id}:
    get:
      tags:
      - API Key Management
      summary: Get key details
      description: Get details for a specific API key.
      operationId: get_api_key
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    patch:
      tags:
      - API Key Management
      summary: Update key metadata
      description: Update the name or description of an API key.
      operationId: update_api_key
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
    delete:
      tags:
      - API Key Management
      summary: Revoke an API key
      description: Revoke an API key. The key will immediately stop working.
      operationId: delete_api_key
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyRevokeResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
  /api/api-keys/{key_id}/revoke:
    post:
      tags:
      - API Key Management
      summary: Revoke an API key (alternative endpoint)
      description: Alternative endpoint to revoke an API key. Same as DELETE /api-keys/{key_id}
      operationId: revoke_api_key
      parameters:
      - name: key_id
        in: path
        required: true
        schema:
          type: string
          title: Key Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyRevokeResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
components:
  schemas:
    ErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
      type: object
      required:
      - error
      title: ErrorSchema
    ApiKeyRefreshRequest:
      properties:
        scope_type:
          type: string
          enum:
          - user
          - project
          - organization
          title: Scope Type
          description: Scope type of the key to refresh
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Project Id
          description: Project ID (required when scope is 'project')
        expires_days:
          type: integer
          maximum: 730.0
          minimum: 1.0
          title: Expires Days
          description: Validity for the new key in days (1-730 days)
          default: 365
      type: object
      required:
      - scope_type
      title: ApiKeyRefreshRequest
      description: Request to refresh (rotate) an API key.
    ApiKeyCreateResponse:
      properties:
        id:
          type: string
          title: Id
          description: Key identifier
        name:
          type: string
          title: Name
          description: Key name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Key description
        key_prefix:
          type: string
          title: Key Prefix
          description: Display-safe key prefix (csk_abc...xyz)
        scope_type:
          type: string
          title: Scope Type
          description: 'Scope type: ''user'', ''project'', or ''organization'''
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Project Id
          description: Project ID for project-scoped keys
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the key was created
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: When the key expires
        last_used_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used At
          description: Last time key was used
        usage_count:
          type: integer
          title: Usage Count
          description: Number of times key was used
        revoked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Revoked At
          description: When key was revoked (if revoked)
        revoked_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked By
          description: User who revoked the key
        is_active:
          type: boolean
          title: Is Active
          description: Whether key is active (not revoked/expired)
        is_revoked:
          type: boolean
          title: Is Revoked
          description: Whether key is revoked
        is_expired:
          type: boolean
          title: Is Expired
          description: Whether key is expired
        key:
          type: string
          title: Key
          description: Full key string (shown only once!)
        warning:
          type: string
          title: Warning
          description: Security warning
          default: Save this key securely. You won't be able to see it again.
      type: object
      required:
      - id
      - name
      - key_prefix
      - scope_type
      - created_at
      - expires_at
      - usage_count
      - is_active
      - is_revoked
      - is_expired
      - key
      title: ApiKeyCreateResponse
      description: Response when creating a new key (includes full key ONCE).
    ApiKeyUpdateRequest:
      properties:
        name:
          anyOf:
          - type: string
            maxLength: 100
            minLength: 1
          - type: 'null'
          title: Name
          description: New key name
        description:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Description
          description: New key description
      type: object
      title: ApiKeyUpdateRequest
      description: Request to update key metadata.
    ApiKeyCreateRequest:
      properties:
        name:
          type: string
          maxLength: 100
          minLength: 1
          title: Name
          description: User-friendly key name
          examples:
          - CI/CD Pipeline
          - Development Server
          - Production API
        description:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Description
          description: Optional description for the key
          examples:
          - Used for automated deployments
          - Local development testing
        expires_days:
          type: integer
          maximum: 730.0
          minimum: 1.0
          title: Expires Days
          description: Key validity in days (1-730 days)
          default: 365
          examples:
          - 30
          - 90
          - 365
        scope_type:
          type: string
          enum:
          - user
          - project
          - organization
          title: Scope Type
          description: 'Scope type: ''user'' for full user permissions, ''project'' for project-scoped, ''organization'' for M2M keys'
          default: user
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Project Id
          description: Project ID (required when scope_type is 'project')
      type: object
      required:
      - name
      title: ApiKeyCreateRequest
      description: Request to create a new API key.
    ApiKeyRevokeResponse:
      properties:
        id:
          type: string
          title: Id
          description: Key identifier
        name:
          type: string
          title: Name
          description: Key name
        revoked_at:
          type: string
          format: date-time
          title: Revoked At
          description: When key was revoked
        revoked_by:
          type: string
          title: Revoked By
          description: User who revoked the key
        message:
          type: string
          title: Message
          description: Success message
          default: API key successfully revoked
      type: object
      required:
      - id
      - name
      - revoked_at
      - revoked_by
      title: ApiKeyRevokeResponse
      description: Response after revoking a key.
    ApiKeyListResponse:
      properties:
        keys:
          items:
            $ref: '#/components/schemas/ApiKeyResponse'
          type: array
          title: Keys
          description: List of keys
        total_count:
          type: integer
          title: Total Count
          description: Total number of keys
        active_count:
          type: integer
          title: Active Count
          description: Number of active keys
        revoked_count:
          type: integer
          title: Revoked Count
          description: Number of revoked keys
      type: object
      required:
      - keys
      - total_count
      - active_count
      - revoked_count
      title: ApiKeyListResponse
      description: Response for listing keys.
    ErrorBody:
      properties:
        message:
          type: string
          title: Message
        type:
          type: string
          title: Type
        details:
          additionalProperties: true
          type: object
          title: Details
          description: Optional extra context for the error.
      type: object
      required:
      - message
      - type
      title: ErrorBody
    ApiKeyResponse:
      properties:
        id:
          type: string
          title: Id
          description: Key identifier
        name:
          type: string
          title: Name
          description: Key name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Key description
        key_prefix:
          type: string
          title: Key Prefix
          description: Display-safe key prefix (csk_abc...xyz)
        scope_type:
          type: string
          title: Scope Type
          description: 'Scope type: ''user'', ''project'', or ''organization'''
        project_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Project Id
          description: Project ID for project-scoped keys
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the key was created
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: When the key expires
        last_used_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Used At
          description: Last time key was used
        usage_count:
          type: integer
          title: Usage Count
          description: Number of times key was used
        revoked_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Revoked At
          description: When key was revoked (if revoked)
        revoked_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Revoked By
          description: User who revoked the key
        is_active:
          type: boolean
          title: Is Active
          description: Whether key is active (not revoked/expired)
        is_revoked:
          type: boolean
          title: Is Revoked
          description: Whether key is revoked
        is_expired:
          type: boolean
          title: Is Expired
          description: Whether key is expired
      type: object
      required:
      - id
      - name
      - key_prefix
      - scope_type
      - created_at
      - expires_at
      - usage_count
      - is_active
      - is_revoked
      - is_expired
      title: ApiKeyResponse
      description: Response for key metadata (without sensitive data).
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter the Bearer token from Clerk authentication
x-tagGroups:
- name: Ingest Your Codebase
  tags:
  - vector_store
  - projects
  - pre_ingestion
  - reingestion
- name: Generate Code Intelligence
  tags:
  - documents
  - document_generation
  - document_formatters
  - prd
  - prd_version
  - tech_spec
  - quality_metrics
  - sample_projects
- name: Query Your Codebase
  tags:
  - conversations
  - workflows
  - discovery
  - context
  - artifacts
- name: Manage and Inspect Intelligence
  tags:
  - api_debugging
  - events
  - version
  - files
  - cache
  - token_tracking
- name: Authenticate and Manage Access
  tags:
  - clerk_authentication
  - github_webhooks
  - github_integration
  - organizations
  - api_key_management
  - mcp_token_management
  - user
- name: (Advanced) Prompt Tuning
  tags:
  - prompts
- name: MCP Protocol
  tags:
  - mcp_protocol
- name: Administration
  tags:
  - admin