247Candle API

A public API for AI, apps and automations to light a virtual candle on 247Candle.

Light a Candle

POST https://www.247candle.com/api/v1/candles/

Create a public candle and receive a shareable candle URL. The endpoint accepts JSON and returns JSON.

curl -X POST https://www.247candle.com/api/v1/candles/ \
  -H "Content-Type: application/json" \
  -d '{
    "for_name": "Anna",
    "message": "For strength and peace today.",
    "name": "Sebastiaan",
    "country": "NL",
    "source": "chatgpt"
  }'

Required Fields

  • for_name: who or what the candle is for
  • name: display name of the person lighting it
  • country: ISO country code, for example NL

Optional Fields

  • message: public candle message
  • theme: active candle theme id, for example 8 for Rose or 24 for Sunflower
  • save_for_history: boolean
  • source: integration label

For AI Agents

Ask only for missing required fields. Do not send sensitive personal data. After creation, show the returned candle URL.

OpenAPI

The machine-readable OpenAPI schema is available at /api/openapi.yaml.

Errors and Limits

Validation errors return 422. Invalid JSON returns 400. Rate-limited requests return 429 with Retry-After and X-RateLimit-* headers.