How AI Agents Can Light a Virtual Candle

An AI agent can now light a virtual candle on 247Candle through the public API. The agent does not need a browser session, a CSRF token, or an admin API. It only needs a small JSON request.

What should the agent ask?

The agent should ask only for missing required information: who the candle is for, the display name to show, and the country code. A message is optional. A theme is optional too, because the API can choose a default candle theme.

What happens after the request?

The API creates the candle and returns a public URL. The agent can then say something simple, such as: your candle has been lit, and here is the link.

What should an AI agent avoid?

An agent should not send sensitive personal data. It should keep the message short, respectful, and suitable for a public candle page. If the user shares private details, the agent should summarize gently or ask whether they want those details included.

How does rate limiting work?

Unauthenticated API use is limited to 10 candle-create requests per IP address per hour. The API returns rate-limit headers so agents know how many requests remain and when to retry.

Where is the schema?

The OpenAPI schema is linked from the 247Candle API page. Agents and automation tools can use it to understand the request and response structure.

For manual use, visit light a candle.