openapi: 3.0.3
info:
  title: SOAT Secrets API
  version: 1.0.0
  description: API for managing encrypted project secrets (Secrets resource)
  contact:
    name: SOAT Team
    url: https://github.com/ttoss/soat
servers:
  - url: '{baseUrl}'
    description: Base URL of your SOAT deployment (e.g. https://your-soat.com or http://localhost:5047)
    variables:
      baseUrl:
        description: The base URL of your SOAT deployment
        default: http://localhost:5047
tags:
  - name: Secrets
    description: Manage secrets
security:
  - bearerAuth: []
paths:
  /api/v1/secrets:
    get:
      tags:
        - Secrets
      summary: List secrets
      description: Returns a list of secrets for a project
      operationId: listSecrets
      parameters:
        - name: project_id
          in: query
          description: Project ID (required if not using project key auth)
          schema:
            type: string
            example: proj_V1StGXR8Z5jdHi6B
        - name: limit
          in: query
          description: Number of results per page
          schema:
            type: integer
            default: 25
        - name: offset
          in: query
          description: Number of results to skip
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of secrets
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    project_id:
                      type: string
                    created_at:
                      type: string
                      format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
    post:
      tags:
        - Secrets
      summary: Create a secret
      description: Creates a new encrypted secret in a project
      operationId: createSecret
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - value
              properties:
                project_id:
                  type: string
                  description: Project ID (required if not using project key auth)
                  example: proj_V1StGXR8Z5jdHi6B
                name:
                  type: string
                  description: Secret name
                  example: DATABASE_PASSWORD
                value:
                  type: string
                  description: Secret value (will be encrypted)
                  example: supersecretpassword
      responses:
        '201':
          description: Secret created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  project_id:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '400':
          description: Bad request (missing required fields)
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Internal server error
  /api/v1/secrets/{secret_id}:
    get:
      tags:
        - Secrets
      summary: Get a secret
      description: Returns a specific secret
      operationId: getSecret
      parameters:
        - name: secret_id
          in: path
          required: true
          description: Secret ID
          schema:
            type: string
            example: secret_V1StGXR8Z5jdHi6B
      responses:
        '200':
          description: Secret details
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  value:
                    type: string
                    description: Decrypted secret value
                  project_id:
                    type: string
                  created_at:
                    type: string
                    format: date-time
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Secret not found
    patch:
      tags:
        - Secrets
      summary: Update a secret
      description: Updates a secret's name and/or value
      operationId: updateSecret
      parameters:
        - name: secret_id
          in: path
          required: true
          description: Secret ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: New secret name
                value:
                  type: string
                  description: New secret value
      responses:
        '200':
          description: Secret updated successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Secret not found
    delete:
      tags:
        - Secrets
      summary: Delete a secret
      description: Deletes a secret
      operationId: deleteSecret
      parameters:
        - name: secret_id
          in: path
          required: true
          description: Secret ID
          schema:
            type: string
      responses:
        '200':
          description: Secret deleted successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Secret not found
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token or sk_ api key