---
openapi: 3.0.3
info:
  title: Flavortown API
  version: v1
  description: You need an API key to use this! Go to your [account settings](https://flavortown.hackclub.com/kitchen?settings=1)
    to get one.
servers:
- url: https://flavortown.hackclub.com/api/v1
security:
- bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Include your API key via `Authorization: Bearer YOUR_API_KEY`.
        You can find or regenerate your API key in your [account settings](https://flavortown.hackclub.com/kitchen?settings=1).'
  schemas:
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
        total_pages:
          type: integer
        total_count:
          type: integer
        next_page:
          type: integer
          nullable: true
    Project:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        description:
          type: string
        repo_url:
          type: string
        demo_url:
          type: string
        readme_url:
          type: string
        ai_declaration:
          type: string
        ship_status:
          type: string
        devlog_ids:
          type: array
          items:
            type: integer
        banner_url:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Comment:
      type: object
      properties:
        id:
          type: integer
        author:
          type: object
          properties:
            id:
              type: integer
            display_name:
              type: string
            avatar:
              type: string
        body:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Devlog:
      type: object
      properties:
        id:
          type: integer
        body:
          type: string
        comments_count:
          type: integer
        duration_seconds:
          type: integer
        likes_count:
          type: integer
        scrapbook_url:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        media:
          type: array
          items:
            type: object
            properties:
              url:
                type: string
              content_type:
                type: string
        comments:
          type: array
          items:
            "$ref": "#/components/schemas/Comment"
    User:
      type: object
      properties:
        id:
          type: integer
        slack_id:
          type: string
        display_name:
          type: string
        avatar:
          type: string
        project_ids:
          type: array
          items:
            type: integer
        cookies:
          type: integer
          nullable: true
    UserDetail:
      allOf:
      - "$ref": "#/components/schemas/User"
      - type: object
        properties:
          vote_count:
            type: integer
          like_count:
            type: integer
          devlog_seconds_total:
            type: integer
          devlog_seconds_today:
            type: integer
    RegionEnabled:
      type: object
      properties:
        enabled_au:
          type: boolean
        enabled_ca:
          type: boolean
        enabled_eu:
          type: boolean
        enabled_in:
          type: boolean
        enabled_uk:
          type: boolean
        enabled_us:
          type: boolean
        enabled_xx:
          type: boolean
    TicketCost:
      type: object
      properties:
        base_cost:
          type: number
        au:
          type: number
        ca:
          type: number
        eu:
          type: number
        in:
          type: number
        uk:
          type: number
        us:
          type: number
        xx:
          type: number
    StoreItem:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        old_prices:
          type: array
          items: {}
        limited:
          type: boolean
        stock:
          type: integer
        type:
          type: string
        show_in_carousel:
          type: boolean
        accessory_tag:
          type: string
        agh_contents:
          type: string
        attached_shop_item_ids:
          type: array
          items: {}
        buyable_by_self:
          type: boolean
        long_description:
          type: string
        max_qty:
          type: integer
        one_per_person_ever:
          type: boolean
        sale_percentage:
          type: integer
        image_url:
          type: string
        enabled:
          "$ref": "#/components/schemas/RegionEnabled"
        ticket_cost:
          "$ref": "#/components/schemas/TicketCost"
    Error:
      type: object
      properties:
        error:
          type: string
    ValidationErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Error"
          example:
            error: Invalid API key
    Forbidden:
      description: Permission denied
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Error"
          example:
            error: Resource not found
    UnprocessableEntity:
      description: Validation failed
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ValidationErrors"
paths:
  "/projects":
    get:
      summary: List projects
      tags:
      - Projects
      description: 'Fetch a list of projects. Ratelimit: 5 reqs/min, 20 reqs/min if
        searching.'
      operationId: listProjects
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number for pagination
      - name: query
        in: query
        required: false
        schema:
          type: string
        description: Search projects by title or description
      responses:
        '200':
          description: A paginated list of projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Project"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
        '401':
          "$ref": "#/components/responses/Unauthorized"
    post:
      summary: Create a project
      tags:
      - Projects
      description: Create a new project.
      operationId: createProject
      parameters: []
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Project"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '422':
          "$ref": "#/components/responses/UnprocessableEntity"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - title
              - description
              properties:
                title:
                  type: string
                  description: Project title
                description:
                  type: string
                  description: Project description
                repo_url:
                  type: string
                  description: URL to the source code repository
                demo_url:
                  type: string
                  description: URL to the live demo
                readme_url:
                  type: string
                  description: URL to the README
                ai_declaration:
                  type: string
                  description: Declaration of AI tools used in this project
        required: true
  "/projects/{id}":
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
    get:
      summary: Get a project
      tags:
      - Projects
      description: 'Fetch a specific project by ID. Ratelimit: 30 reqs/min.'
      operationId: getProject
      responses:
        '200':
          description: A single project
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Project"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
    patch:
      summary: Update a project
      tags:
      - Projects
      description: Update an existing project.
      operationId: updateProject
      parameters: []
      responses:
        '200':
          description: Project updated
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Project"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '403':
          "$ref": "#/components/responses/Forbidden"
        '404':
          "$ref": "#/components/responses/NotFound"
        '422':
          "$ref": "#/components/responses/UnprocessableEntity"
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: Project title
                description:
                  type: string
                  description: Project description
                repo_url:
                  type: string
                  description: URL to the source code repository
                demo_url:
                  type: string
                  description: URL to the live demo
                readme_url:
                  type: string
                  description: URL to the README
                ai_declaration:
                  type: string
                  description: Declaration of AI tools used in this project
        required: true
  "/projects/{project_id}/devlogs":
    get:
      summary: List project devlogs
      tags:
      - Projects
      description: Fetch all devlogs for a specific project.
      operationId: listProjectDevlogs
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A paginated list of devlogs for the project
          content:
            application/json:
              schema:
                type: object
                properties:
                  devlogs:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Devlog"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/devlogs":
    get:
      summary: List devlogs
      tags:
      - Devlogs
      description: Fetch all devlogs across all projects.
      operationId: listDevlogs
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number for pagination
      responses:
        '200':
          description: A paginated list of devlogs
          content:
            application/json:
              schema:
                type: object
                properties:
                  devlogs:
                    type: array
                    items:
                      "$ref": "#/components/schemas/Devlog"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/devlogs/{id}":
    get:
      summary: Get a devlog
      tags:
      - Devlogs
      description: Fetch a devlog by ID.
      operationId: getDevlog
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A single devlog
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Devlog"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/store":
    get:
      summary: List store items
      tags:
      - Store
      description: 'Fetch a list of store items. Ratelimit: 5 reqs/min.'
      operationId: listStoreItems
      responses:
        '200':
          description: A list of store items
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/StoreItem"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/store/{id}":
    get:
      summary: Get a store item
      tags:
      - Store
      description: 'Fetch a specific store item by ID. Ratelimit: 30 reqs/min.'
      operationId: getStoreItem
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A single store item
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/StoreItem"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"
  "/users":
    get:
      summary: List users
      tags:
      - Users
      description: 'Fetch a list of users. Ratelimit: 5 reqs/min.'
      operationId: listUsers
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
        description: Page number for pagination
      - name: query
        in: query
        required: false
        schema:
          type: string
        description: Search users by display name or slack ID
      responses:
        '200':
          description: A paginated list of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      "$ref": "#/components/schemas/User"
                  pagination:
                    "$ref": "#/components/schemas/Pagination"
        '401':
          "$ref": "#/components/responses/Unauthorized"
  "/users/{id}":
    get:
      summary: Get a user
      tags:
      - Users
      description: Fetch a specific user by ID. Use "me" as the ID to fetch the authenticated
        user.
      operationId: getUser
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: User ID or "me" for the authenticated user
      responses:
        '200':
          description: A single user with additional stats
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/UserDetail"
        '401':
          "$ref": "#/components/responses/Unauthorized"
        '404':
          "$ref": "#/components/responses/NotFound"