openapi: 3.2.0
info:
  title: Karada Admin API
  version: 1.0.0
  description: Spec-Driven API definition for Karada MCP Platform
servers:
- url: https://api.karada.ai
  description: Production API
- url: http://localhost:8080
  description: Local development API
tags:
- name: Admin
paths:
  /api/v1/user/admin/users:
    get:
      summary: List all users (admin only)
      operationId: listUsersAdmin
      tags:
      - Admin
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string
                    email:
                      type: string
                    role:
                      type: string
                    avatar_url:
                      type: string
                    created_at:
                      type: string
                      format: date-time
  /api/v1/admin/claims:
    get:
      summary: List pending claim requests (admin only)
      operationId: listAdminClaims
      tags:
      - Admin
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Pending claim requests
  /api/v1/admin/claims/{id}/approve:
    post:
      summary: Approve claim request (admin only)
      operationId: approveAdminClaim
      tags:
      - Admin
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Claim approved
  /api/v1/admin/claims/{id}/reject:
    post:
      summary: Reject claim request (admin only)
      operationId: rejectAdminClaim
      tags:
      - Admin
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Claim rejected
  /api/v1/admin/upgrade-team:
    post:
      summary: Manually upgrade a team's pricing tier
      operationId: adminUpgradeTeam
      tags:
      - Admin
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - team_id
              - tier_slug
              properties:
                team_id:
                  type: string
                  format: uuid
                tier_slug:
                  type: string
      responses:
        '200':
          description: Team upgraded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  team_id:
                    type: string
                    format: uuid
                  tier:
                    type: string
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /api/v1/admin/teams:
    get:
      summary: List all teams for admin management
      operationId: listAdminTeams
      tags:
      - Admin
      security:
      - BearerAuth: []
      responses:
        '200':
          description: List of all teams
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string
                    slug:
                      type: string
                    tier_slug:
                      type: string
                    created_at:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /api/v1/admin/upgrade-requests:
    get:
      summary: List upgrade requests
      operationId: listAdminUpgradeRequests
      tags:
      - Admin
      security:
      - BearerAuth: []
      parameters:
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - pending
          - approved
          - rejected
      responses:
        '200':
          description: List of upgrade requests
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    team_id:
                      type: string
                      format: uuid
                    team_name:
                      type: string
                    user_id:
                      type: string
                      format: uuid
                    user_name:
                      type: string
                    user_email:
                      type: string
                    tier_slug:
                      type: string
                    status:
                      type: string
                    notes:
                      type: string
                    created_at:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
  /api/v1/admin/upgrade-requests/{id}/approve:
    post:
      summary: Approve upgrade request
      operationId: approveAdminUpgradeRequest
      tags:
      - Admin
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request approved
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
  /api/v1/admin/upgrade-requests/{id}/reject:
    post:
      summary: Reject upgrade request
      operationId: rejectAdminUpgradeRequest
      tags:
      - Admin
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Request rejected
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  status:
                    type: string
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT