openapi: 3.2.0
info:
  title: Karada Projects 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: Projects
paths:
  /api/v1/projects/create:
    post:
      summary: Create new project
      operationId: createProject
      tags:
      - Projects
      security:
      - BearerAuth: []
      responses:
        '201':
          description: Project created
  /api/v1/projects/list:
    get:
      summary: List projects for active team
      operationId: listProjects
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: team_id
        in: query
        required: false
        description: Team UUID to list projects for. If omitted, defaults to user's primary team.
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        required: false
        description: Number of projects to return (max 100)
        schema:
          type: integer
          default: 20
      - name: offset
        in: query
        required: false
        description: Number of projects to skip
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of projects
  /api/v1/projects/{slug}:
    get:
      summary: Get project by slug
      operationId: getProjectBySlug
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Project details
    put:
      summary: Update project by slug
      operationId: updateProjectBySlug
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated project
    delete:
      summary: Delete project by slug
      operationId: deleteProjectBySlug
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Project deleted
  /api/v1/projects/{slug}/publish:
    post:
      summary: Publish project to registry / marketplace
      operationId: publishProject
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Project published
  /api/v1/projects/{slug}/sync:
    post:
      summary: Re-sync OpenAPI/Postman spec from source URL and optionally redeploy
      operationId: syncProjectSpec
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                redeploy:
                  type: boolean
                  description: Whether to automatically trigger a new deployment after sync
      responses:
        '200':
          description: Spec synchronized successfully
  /api/v1/projects/{slug}/export:
    get:
      summary: Export and download MCP Server source bundle in specified language
      operationId: exportProjectMCP
      tags:
      - Projects
      security:
      - BearerAuth: []
      parameters:
      - name: slug
        in: path
        required: true
        schema:
          type: string
      - name: language
        in: query
        required: false
        schema:
          type: string
          enum:
          - typescript
          - go
          - python
          default: typescript
      responses:
        '200':
          description: Generated ZIP archive
          content:
            application/zip:
              schema:
                type: string
                format: binary
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT