openapi: 3.1.0
info:
  title: 247Candle Public API
  version: 1.0.0
  description: Public API for lighting virtual candles on 247Candle.
servers:
  - url: https://www.247candle.com
paths:
  /api/v1/candles/:
    post:
      operationId: createCandle
      summary: Light a virtual candle
      description: Creates a normal public 247Candle candle and returns a shareable candle URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCandleRequest'
            examples:
              minimal:
                value:
                  for_name: Anna
                  name: Sebastiaan
                  country: NL
              full:
                value:
                  for_name: Anna
                  message: For strength and peace today.
                  name: Sebastiaan
                  country: NL
                  theme: "8"
                  save_for_history: false
                  source: chatgpt
      responses:
        "201":
          description: Candle created.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candle'
        "400":
          description: Invalid JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "415":
          description: Unsupported media type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "422":
          description: Validation error.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "429":
          description: Rate limited.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds to wait before retrying.
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "500":
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateCandleRequest:
      type: object
      additionalProperties: false
      required:
        - for_name
        - name
        - country
      properties:
        for_name:
          type: string
          minLength: 1
          description: Name or intention the candle is for. 247Candle stores only the first word.
        message:
          type: string
          description: Optional public candle message. Do not send sensitive personal data.
        name:
          type: string
          minLength: 1
          description: Display name of the person lighting the candle. 247Candle stores only the first word.
        country:
          type: string
          minLength: 2
          maxLength: 2
          description: ISO 3166-1 alpha-2 country code.
        theme:
          type: string
          enum:
            - "8"
            - "4"
            - "11"
            - "9"
            - "21"
            - "24"
            - "41"
            - "40"
            - "6"
            - "16"
            - "20"
            - "15"
            - "14"
            - "17"
            - "42"
            - "13"
          x-enumNames:
            - Rose
            - Love
            - Gerbera
            - Blossom
            - Butterfly
            - Sunflower
            - Birds
            - Waves
            - Jesus of Nazareth
            - Maria Magdalene
            - Abraham's Journey
            - Hinduism
            - Buddhism
            - Native American Spiritualism
            - Daoism
            - Spiritualism
          description: Optional active candle theme media_id. If omitted, 247Candle uses the first active candle theme.
        save_for_history:
          type: boolean
          default: false
          description: Whether the candle can remain visible after the normal active period.
        source:
          type: string
          maxLength: 50
          default: api
          description: Integration label, for example chatgpt, zapier, make, n8n, or partner name.
    Candle:
      type: object
      required:
        - id
        - object
        - url
        - created_at
        - expires_at
        - status
      properties:
        id:
          type: integer
        object:
          type: string
          const: candle
        url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - published
        theme:
          type: string
        source:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            fields:
              type: object
              additionalProperties:
                type: string
