openapi: 3.0.3
info:
  title: Evento Public API
  description: |
    The Evento Public API provides programmatic access to public event data from the Evento platform. 
    This RESTful API allows developers to retrieve event information, user events, and build integrations with Evento.
  version: 1.0.0
  contact:
    email: api-support@evento.so
  license:
    name: Proprietary
    url: https://evento.so/terms

servers:
  - url: https://api.evento.so/api/public/v1
    description: Production server
  - url: https://staging-api.evento.so/api/public/v1
    description: Staging server

security:
  - apiKey: []

tags:
  - name: Events
    description: Operations related to individual events
  - name: Users
    description: Operations related to user events and profiles

paths:
  /events/{eventId}:
    get:
      tags:
        - Events
      summary: Get event by ID
      description: Retrieve detailed information about a specific event
      operationId: getEventById
      parameters:
        - name: eventId
          in: path
          description: Unique identifier of the event
          required: true
          schema:
            type: string
            example: evt_abc123
      responses:
        '200':
          description: Event details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{username}/events:
    get:
      tags:
        - Users
      summary: Get user's created events
      description: Retrieve all public events created by a specific user
      operationId: getUserEvents
      parameters:
        - name: username
          in: path
          description: Username of the user
          required: true
          schema:
            type: string
            example: johndoe
        - name: since
          in: query
          description: Filter events starting from this date (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: from
          in: query
          description: Alias for 'since' parameter
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-01-01T00:00:00Z'
        - name: to
          in: query
          description: Filter events up to this date (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
            example: '2024-12-31T23:59:59Z'
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{username}/profile-events:
    get:
      tags:
        - Users
      summary: Get user's profile events
      description: Retrieve all events created by or RSVP'd to by a user
      operationId: getUserProfileEvents
      parameters:
        - name: username
          in: path
          description: Username of the user
          required: true
          schema:
            type: string
            example: johndoe
        - name: since
          in: query
          description: Filter events starting from this date (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
        - name: from
          in: query
          description: Alias for 'since' parameter
          required: false
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          description: Filter events up to this date (ISO 8601 format)
          required: false
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Profile events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{username}/upcoming-events:
    get:
      tags:
        - Users
      summary: Get user's upcoming events
      description: Retrieve upcoming events hosted by a specific user
      operationId: getUserUpcomingEvents
      parameters:
        - name: username
          in: path
          description: Username of the user
          required: true
          schema:
            type: string
            example: johndoe
        - name: limit
          in: query
          description: Number of results to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            example: 10
        - name: offset
          in: query
          description: Number of results to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
      responses:
        '200':
          description: Upcoming events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /users/{username}/past-events:
    get:
      tags:
        - Users
      summary: Get user's past events
      description: Retrieve past events hosted by a specific user, ordered by most recent first
      operationId: getUserPastEvents
      parameters:
        - name: username
          in: path
          description: Username of the user
          required: true
          schema:
            type: string
            example: johndoe
        - name: limit
          in: query
          description: Number of results to return
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
            example: 10
        - name: offset
          in: query
          description: Number of results to skip for pagination
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
      responses:
        '200':
          description: Past events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-evento-api-key
      description: API key for authentication

  schemas:
    Event:
      type: object
      required:
        - id
        - title
        - description
        - cover
        - location
        - start_date
        - timezone
        - status
        - visibility
        - created_at
        - creator
        - links
        - contributions
      properties:
        id:
          type: string
          description: Unique event identifier
          example: evt_abc123
        title:
          type: string
          description: Event title
          example: Tech Meetup 2024
        description:
          type: string
          description: Event description (may contain markdown)
          example: Join us for an evening of tech talks and networking
        cover:
          type: string
          format: uri
          description: URL to event cover image
          example: https://example.com/event-cover.jpg
        location:
          type: string
          description: Event location (address or venue name)
          example: San Francisco, CA
        start_date:
          type: string
          format: date-time
          description: Event start date/time (ISO 8601)
          example: '2024-12-15T18:00:00Z'
        end_date:
          type: string
          format: date-time
          nullable: true
          description: Event end date/time (ISO 8601)
          example: '2024-12-15T21:00:00Z'
        timezone:
          type: string
          description: Event timezone (IANA timezone)
          example: America/Los_Angeles
        status:
          type: string
          enum: [published]
          description: Event status (always "published" for public API)
          example: published
        visibility:
          type: string
          enum: [public]
          description: Event visibility (always "public" for public API)
          example: public
        cost:
          type: number
          format: float
          nullable: true
          description: Event cost in USD (null = free)
          example: 25.00
        created_at:
          type: string
          format: date-time
          description: Event creation timestamp (ISO 8601)
          example: '2024-11-01T10:00:00Z'
        creator:
          $ref: '#/components/schemas/Creator'
        links:
          $ref: '#/components/schemas/EventLinks'
        contributions:
          $ref: '#/components/schemas/Contributions'

    Creator:
      type: object
      required:
        - id
        - username
        - image
      properties:
        id:
          type: string
          description: User ID
          example: usr_xyz789
        username:
          type: string
          description: Username
          example: johndoe
        image:
          type: string
          format: uri
          description: Profile image URL
          example: https://example.com/avatar.jpg
        verification_status:
          type: string
          nullable: true
          description: User verification status
          example: verified

    EventLinks:
      type: object
      properties:
        spotify_url:
          type: string
          format: uri
          nullable: true
          description: Spotify playlist URL
          example: https://spotify.com/playlist/abc123
        wavlake_url:
          type: string
          format: uri
          nullable: true
          description: Wavlake URL
          example: null

    Contributions:
      type: object
      properties:
        cashapp:
          type: string
          nullable: true
          description: CashApp handle
          example: $johndoe
        venmo:
          type: string
          nullable: true
          description: Venmo handle
          example: '@johndoe'
        paypal:
          type: string
          nullable: true
          description: PayPal email or handle
          example: johndoe@example.com
        btc_lightning:
          type: string
          nullable: true
          description: Bitcoin Lightning address
          example: null

    EventResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
          example: true
        message:
          type: string
          description: Descriptive message about the response
          example: Event details fetched successfully
        data:
          $ref: '#/components/schemas/Event'

    EventsListResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
          example: true
        message:
          type: string
          description: Descriptive message about the response
          example: Events fetched successfully for user johndoe
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'

    ErrorResponse:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          description: Always false for errors
          example: false
        message:
          type: string
          description: Error description
          example: Username is required

    ValidationError:
      type: object
      required:
        - success
        - message
        - errors
      properties:
        success:
          type: boolean
          description: Always false for validation errors
          example: false
        message:
          type: string
          description: General error message
          example: Validation failed
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that failed validation
                example: limit
              message:
                type: string
                description: Validation error message
                example: Limit must be between 1 and 100