Luma - Charter Docs

74 toolsAPI key

luma_example.py

import asyncio
import os

from charter.packs import luma

luma.configure(api_key=os.environ["LUMA_API_KEY"])

async def main():
    going = await luma.events_guests_list.ainvoke(event_id="evt-...", approval_status="approved")

asyncio.run(main())

Luma runs event pages and the calendars that list them. This API is how a program does what an organizer does in the app: create and update events, add and approve guests, issue ticket types and coupons, email the guest list, and manage the calendar’s contacts, tags, admins and memberships. The pack was drafted from Luma’s own OpenAPI document by scripts/openapi_to_pack.py, so every parameter, enum member and description is Luma’s, word for word. What a spec cannot carry — the rules Luma states in prose, the sentences a blank parameter needed, the limits below — was added in review.

Authenticating

Get a key: at luma.com/calendar/manage/api-keys choose the calendar and generate a key — it reaches that calendar only, and the API needs a Luma Plus subscription — then export LUMA_API_KEY=…. This pack takes an API key in x-luma-api-key, and configure() is optional when $LUMA_API_KEY is set. That key serves every call the process makes. For an application whose users each connect their own account, hand configure() a credential_provider instead — a SubjectProvider that answers per user — and each call carries the credential of the user use_subject names. Your users’ accounts says how each pack’s users connect. A calendar key reaches the calendar it was made on and nothing else, so the calendars_* tools act on that calendar and only calendars_update asks for its ID. An organization key reaches the organizations_* tools. Where Luma documents choosing one of the organization’s calendars — approving or rejecting a submission — it is a header, and which calendar a call acts on is your decision, not the model’s, so pass it per call rather than as an argument:

await luma.calendars_events_approve.ainvoke(
    {"calendar_event_id": "calev-..."}, headers={"x-luma-calendar-id": "cal-..."}
)

The client

oauth_tool_factory is the whole client: a thin wrapper over httpx that attaches your key and these endpoint constants to each request. No vendor SDK enters your dependency tree.

import os

from charter import oauth_tool_factory
from charter.auth import StaticTokenProvider

api_key = os.environ["LUMA_API_KEY"]

luma_api_client = oauth_tool_factory(
    base_url="https://public-api.luma.com/",
    provider="luma",
    credential_provider=StaticTokenProvider(api_key),
    # the token is not sent in Authorization
    token_header="x-luma-api-key",
    pack="luma",
    body_format="json",
    query_format="repeat",
    body_case="snake",
    query_case="snake",
    path_case="snake",
    # this API reports failure with an HTTP status code
    envelope=None,
)

import os

from charter.packs import luma

luma.configure(api_key=os.environ["LUMA_API_KEY"])

# The base URL, the casing, the envelope and the pagination are
# already declared. 74 tools, ready to hand to a model:
tools = luma.TOOLS

Paging through a list

A cursor belongs to the tool that returns it, so it is declared on that tool’s builder call:

luma_pagination.py

calendars_events_list = luma_api_client(
    name="calendars_events_list",
    args_schema=CalendarsEventsListRequest,
    method="GET",
    url_template="v1/calendars/events/list",
    pagination=Pagination(
        cursor_field="next_cursor",
        cursor_param="pagination_cursor",
        more_field="has_more",
    ),
)

Pagination is declared on calendars_events_list, events_guests_list, images_search, calendars_contacts_list, events_coupons_list, calendars_coupons_list, memberships_tiers_list, webhooks_list, organizations_calendars_list and organizations_events_list. The other 64 take no cursor.

Reads are GETs with query parameters and every write is a POST. Luma versions each route on its own, so /v1/ and /v2/ sit side by side and the version is part of each tool’s URL. Failure is an HTTP status — 429 past the rate limit of 200 requests a minute per calendar key — and the ten list tools page on has_more, sending next_cursor back as pagination_cursor.

Limits

null cannot be sent. Charter omits an unset field rather than sending null, so what Luma clears with null — an event’s font, a registration question’s library source, a calendar’s location, a ticket type’s max_per_guest — can be set through these tools but not cleared.
Uploading an image is two steps, and the second is not a tool. images_create_upload_url returns an upload_url to PUT the bytes to, which is a file transfer to Luma’s CDN rather than an API call.
events_create and events_update are large, about 22KB of schema each, mostly themes, fonts and the thirteen kinds of registration question. A projection keeps what an agent uses.

Tools

Each is a Tool, called with ainvoke as in the snippet above.

​Authenticating

​The client

​Paging through a list

​Limits

​Tools

Authenticating

The client

Paging through a list

Limits

Tools