openapi.yaml

openapi: 3.1.0
x-stoplight:
  id: 1x4ipstekin0w

info:
  title: LibPulse Platform API
  version: 0.1.0
  description: |
    LibPulse Platform API — MVP version.
    This specification describes the backend API for developer authentication
    and future ingestion / dashboard services.

servers:
  - url: 'http://localhost:8080'
    description: Local development

tags:
  - name: Me
    description: Endpoints related to the authenticated user
  - name: Projects
    description: Project management endpoints
  - name: Health
    description: API health endpoints (future extension)

paths:
  /api/v1/me:
    get:
      tags: [Me]
      summary: Get current authenticated user
      description: |
        Return the authenticated user's profile based on the JWT token supplied
        in the Authorization header (`Bearer <token>`).
      operationId: getCurrentUser
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Current user profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-stoplight:
        id: d9om0yu3ebh28

  /api/v1/projects:
    post:
      tags: [Projects]
      summary: Create project
      description: Create a new project for the authenticated user.
      operationId: createProject
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
            examples:
              demo:
                value:
                  name: demo
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProjectResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - duplicate project name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/projects/{id}/keys:
    post:
      tags: [Projects]
      summary: Create project key
      description: |
        Issue a new key for a project.
        Only the project owner can create keys.

        **Rate Limits:**
        - Maximum 3 key creations per minute (burst protection)
        - Maximum 5 key creations per day (daily quota)

        Both limits must be satisfied. Exceeding either limit returns HTTP 429.
      operationId: createProjectKey
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          description: Project ID
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectKeyRequest'
            examples:
              ciProd:
                value:
                  label: pixi-prod-ci
                  env: prod
                  require_signature: true
                  scopes: [ingest]
      responses:
        '201':
          description: Created
          headers:
            Cache-Control:
              schema:
                type: string
              example: no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProjectKeyResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded (either 3/minute or 5/day limit)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      description: Authenticated user profile
      required: [id, email, provider, createdAt]
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
          nullable: true
        avatarUrl:
          type: string
          format: uri
          nullable: true
        provider:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      x-stoplight:
        id: cbluz1ujcurnu

    CreateProjectRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64

    CreateProjectResponse:
      type: object
      required: [id]
      properties:
        id:
          type: string
          format: uuid

    ProjectKeyScope:
      type: string
      enum: [ingest]

    CreateProjectKeyRequest:
      type: object
      additionalProperties: false
      required: [label]
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 64
        require_signature:
          type: boolean
          default: false
        env:
          type: string
          nullable: true
        scopes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ProjectKeyScope'
          default: [ingest]

    ProjectKey:
      type: object
      required: [id, label, scopes, secret_last4, created_at]
      properties:
        id:
          type: string
        label:
          type: string
        env:
          type: string
          nullable: true
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/ProjectKeyScope'
        secret_last4:
          type: string
        created_at:
          type: string
          format: date-time

    CreateProjectKeyResponse:
      type: object
      required: [project_key_public, key]
      properties:
        project_key_public:
          type: string
        project_secret:
          type: string
          nullable: true
        key:
          $ref: '#/components/schemas/ProjectKey'

    ErrorResponse:
      type: object
      required: [error, code]
      properties:
        error:
          type: string
        code:
          type: string
      x-stoplight:
        id: 7wotubcs0l2ll

x-internal: false