openapi: 3.0.3
info:
  title: Agentic Terraforming API
  description: REST API for agent lifecycle, system tools, integrations, and sensory control
  version: 1.1.0
  contact:
    name: API Support
    email: devops@agentic.terra
servers:
  - url: http://localhost:7860/api
    description: Development server
  - url: https://api.agentic.terra/v1
    description: Production server
paths:
  /agent/upload-spreadsheet:
    post:
      tags: [Agent Control]
      summary: Upload spreadsheet for trait processing
      security:
        - OAuthToken: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: CSV/XLSX file with agent traits
      responses:
        '202':
          description: Upload accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobTicket'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    OAuthToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    JobTicket:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status_url:
          type: string
          format: uri
          description: URL to poll for job status
      required: [job_id]
  responses:
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Invalid OAuth token"
security:
  - OAuthToken: []
  - ApiKey: []