openapi: 3.0.3
info:
  title: 200Notes API
  description: |
    The 200Notes API provides programmatic access to project management, note taking, and team collaboration features.
    
    ## Authentication
    All protected endpoints require Bearer token authentication using the format: `api_key:api_secret`
    
    ## Current Implementation Status
    - ✅ Authentication: Fully implemented
    - ✅ Projects: Fully implemented  
    - ✅ Team Management: Routes implemented (some methods pending)
    - 🚧 Notes: Coming in Phase 2
    - 🚧 Tasks: Coming in Phase 2
    - 🚧 AI Features: Coming in Phase 3
  version: 1.0.0
  contact:
    name: 200Notes Support
    url: https://200notes.com/support
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://200notes.com/api/v1
    description: Production API server

paths:
  /auth/register:
    post:
      tags:
        - Authentication
      summary: Register new account
      description: Create a new user account and receive API credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - email
                - password
                - password_confirmation
              properties:
                name:
                  type: string
                  description: User's full name
                  example: "John Doe"
                email:
                  type: string
                  format: email
                  description: Valid email address
                  example: "john@example.com"
                password:
                  type: string
                  minLength: 8
                  description: Password (minimum 8 characters)
                  example: "securepassword123"
                password_confirmation:
                  type: string
                  description: Password confirmation
                  example: "securepassword123"
      responses:
        '201':
          description: Registration successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Registration successful"
                  data:
                    type: object
                    properties:
                      user:
                        $ref: '#/components/schemas/User'
                      api_key:
                        type: string
                        example: "sk-abc123"
                      api_secret:
                        type: string
                        example: "xyz789"
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

  /auth/login:
    post:
      tags:
        - Authentication
      summary: Login
      description: Authenticate and receive API credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - password
              properties:
                email:
                  type: string
                  format: email
                  example: "john@example.com"
                password:
                  type: string
                  example: "securepassword123"
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Login successful"
                  data:
                    type: object
                    properties:
                      user:
                        $ref: '#/components/schemas/User'
                      api_key:
                        type: string
                        example: "sk-abc123"
                      api_secret:
                        type: string
                        example: "xyz789"
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/refresh-keys:
    post:
      tags:
        - Authentication
      summary: Refresh API keys
      description: Generate new API credentials (invalidates current keys)
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Keys refreshed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "API keys refreshed successfully"
                  data:
                    type: object
                    properties:
                      api_key:
                        type: string
                        example: "sk-def456"
                      api_secret:
                        type: string
                        example: "uvw012"
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /projects:
    get:
      tags:
        - Projects
      summary: List projects
      description: Get all projects the authenticated user has access to
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Projects retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectSummary'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

    post:
      tags:
        - Projects
      summary: Create project
      description: Create a new project
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Project name
                  example: "Marketing Campaign"
                description:
                  type: string
                  description: Project description
                  example: "Q1 marketing campaign planning"
      responses:
        '201':
          description: Project created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Project created successfully"
                  data:
                    $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

  /projects/{projectId}:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Project UUID
        example: "550e8400-e29b-41d4-a716-446655440000"

    get:
      tags:
        - Projects
      summary: Get project
      description: Get details of a specific project
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Project retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ProjectDetail'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

    put:
      tags:
        - Projects
      summary: Update project
      description: Update an existing project
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 255
                  description: Project name
                  example: "Updated Project Name"
                description:
                  type: string
                  description: Project description
                  example: "Updated project description"
      responses:
        '200':
          description: Project updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Project updated successfully"
                  data:
                    $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'

    delete:
      tags:
        - Projects
      summary: Delete project
      description: Delete a project (owner only)
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Project deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Project deleted successfully"
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /projects/{projectId}/favorite:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Project UUID

    post:
      tags:
        - Projects
      summary: Toggle project favorite
      description: Toggle the favorite status of a project
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Favorite status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "Project favorite status updated"
                  data:
                    type: object
                    properties:
                      is_favorite:
                        type: boolean
                        example: true
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /projects/{projectId}/invite:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Project UUID

    post:
      tags:
        - Team Management
      summary: Invite team member
      description: Invite a user to join the project
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - role
              properties:
                email:
                  type: string
                  format: email
                  description: Email of user to invite
                  example: "teammate@example.com"
                role:
                  type: string
                  enum: [editor, viewer]
                  description: Role to assign to the invited user
                  example: "editor"
      responses:
        '200':
          description: Invitation sent successfully
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

  /projects/{projectId}/members:
    parameters:
      - name: projectId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Project UUID

    get:
      tags:
        - Team Management
      summary: List project members
      description: Get list of all project members
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Members retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProjectMember'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: 'api_key:api_secret'
      description: 'Bearer token in format: api_key:api_secret'

  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "John Doe"
        email:
          type: string
          format: email
          example: "john@example.com"
        created_at:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00.000000Z"

    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: "550e8400-e29b-41d4-a716-446655440000"
        name:
          type: string
          example: "Marketing Campaign"
        description:
          type: string
          example: "Q1 marketing campaign planning"
        is_favorite:
          type: boolean
          example: false
        owner_id:
          type: integer
          example: 1
        created_at:
          type: string
          format: date-time
          example: "2024-01-15T10:30:00.000000Z"
        updated_at:
          type: string
          format: date-time
          example: "2024-01-16T14:20:00.000000Z"

    ProjectSummary:
      allOf:
        - $ref: '#/components/schemas/Project'
        - type: object
          properties:
            owner:
              $ref: '#/components/schemas/User'

    ProjectDetail:
      allOf:
        - $ref: '#/components/schemas/ProjectSummary'
        - type: object
          properties:
            role:
              type: string
              enum: [owner, editor, viewer]
              example: "owner"

    ProjectMember:
      type: object
      properties:
        id:
          type: integer
          example: 2
        name:
          type: string
          example: "Jane Smith"
        email:
          type: string
          format: email
          example: "jane@example.com"
        role:
          type: string
          enum: [owner, editor, viewer]
          example: "editor"
        joined_at:
          type: string
          format: date-time
          example: "2024-01-16T09:15:00.000000Z"

    Error:
      type: object
      properties:
        message:
          type: string
          example: "Unauthenticated."

    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: "Validation failed"
        messages:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            name:
              - "The name field is required."

  responses:
    UnauthorizedError:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    ForbiddenError:
      description: Access denied
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: "Access denied"

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "No query results for model [App\\Models\\Project]"

tags:
  - name: Authentication
    description: User authentication and API key management
  - name: Projects
    description: Project management operations
  - name: Team Management
    description: Project collaboration and team member management