openapi: 3.0.3
info:
  title: Prompt Architect API
  description: |
    Prompt engineering services API for AI agents and autonomous systems.
    
    ## The Prompt Contract Method
    A 4-component framework for reproducible AI outputs:
    1. GOAL — Exact success metrics
    2. CONSTRAINTS — Hard boundaries
    3. FORMAT — Output structure
    4. FAILURE — Guardrails
    
  version: 1.0.0
  contact:
    name: Prompt Architect (Jarvis)
    email: jarvis@promptarchitect.site
    url: https://promptarchitect.site

servers:
  - url: https://promptarchitect.site
    description: Production server

tags:
  - name: agent-services
    description: Services for AI agents and LLMs
  - name: starter-kit
    description: Free starter kit download

paths:
  /api/agent-services:
    post:
      tags:
        - agent-services
      summary: Submit agent service request
      description: |
        Request a prompt engineering service for your AI agent system.
        
        Service IDs:
        - MAC-001: Multi-Agent Coordination Protocol ($499, 48h)
        - MEM-002: Memory Architecture System ($399, 72h)
        - OUT-003: Output Optimization Framework ($299, 24h)
        - SEC-004: Agent Security Protocol ($599, 96h)
        - PER-005: Persona Engineering System ($349, 36h)
        - TOK-006: Token Optimization Engine ($249, 12h)
      operationId: submitAgentService
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentServiceRequest'
            examples:
              crewai:
                summary: CrewAI Integration
                value:
                  service_id: MAC-001
                  agent_identity:
                    name: ResearchAgent-v2
                    framework: crewai
                    version: "0.28.0"
                  current_state:
                    prompts:
                      - current_prompt_1.txt
                      - current_prompt_2.txt
                    memory_system:
                      type: postgres
                      table: agent_memory
                    output_formats:
                      - json
                  optimization_goals:
                    - reduce_token_usage
                    - improve_consistency
                  constraints:
                    max_tokens: 2000
                    framework_version: "0.28.0"
                  operator_email: developer@company.com
      responses:
        '200':
          description: Request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentServiceResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /api/starter-kit:
    post:
      tags:
        - starter-kit
      summary: Download free starter kit
      description: |
        Get the Prompt Architect's Starter Kit with framework templates.
        
        Idempotency: Requests are keyed by normalized email address.
      operationId: getStarterKit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address for delivery
                name:
                  type: string
                  description: Optional name
      responses:
        '200':
          description: Starter kit sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  download_url:
                    type: string
                    format: uri
        '400':
          description: Invalid email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    AgentServiceRequest:
      type: object
      required:
        - service_id
        - agent_identity
        - operator_email
      properties:
        service_id:
          type: string
          enum:
            - MAC-001
            - MEM-002
            - OUT-003
            - SEC-004
            - PER-005
            - TOK-006
          description: Service identifier
        agent_identity:
          $ref: '#/components/schemas/AgentIdentity'
        current_state:
          $ref: '#/components/schemas/CurrentState'
        optimization_goals:
          type: array
          items:
            type: string
          description: Goals for optimization
        constraints:
          type: object
          additionalProperties: true
          description: Constraints for the solution
        operator_email:
          type: string
          format: email
          description: Human operator email for billing and delivery

    AgentIdentity:
      type: object
      required:
        - name
        - framework
      properties:
        name:
          type: string
          description: Agent name or identifier
        framework:
          type: string
          enum:
            - crewai
            - autogen
            - langgraph
            - langchain
            - semantic-kernel
            - custom
          description: Agent framework
        version:
          type: string
          description: Framework version

    CurrentState:
      type: object
      properties:
        prompts:
          type: array
          items:
            type: string
          description: Current prompt files or content
        memory_system:
          type: object
          additionalProperties: true
          description: Current memory architecture
        output_formats:
          type: array
          items:
            type: string
          description: Required output formats

    AgentServiceResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - processing
            - queued
            - delivered
        estimated_delivery:
          type: string
          format: date-time
        deliverables:
          type: array
          items:
            type: string
        integration_notes:
          type: string

    Error:
      type: object
      properties:
        error:
          type: string
          enum:
            - invalid_json
            - missing_email
            - invalid_email
            - invalid_operator_email
            - missing_required_fields
            - rate_limited
            - not_found
        message:
          type: string
        details:
          type: object
          additionalProperties: true

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key (not required for public beta)

security:
  - ApiKeyAuth: []
