Fevori

Fevori API

Manage your events and guest lists from your own scripts and AI agents: create events, add and update guests, and see who has replied.

Getting started

  1. Create an API key on your account page. It’s shown once, so copy it somewhere safe.
  2. Send it with every request as Authorization: Bearer fev_….
  3. Or use OAuth instead of a key: apps can send people to sign in with Google and get a token for resource https://fevori.app that can do only what they allow. See /auth.md and the oauth2 scheme in the OpenAPI description.
  4. Send request bodies as JSON. Responses are JSON too.

For AI agents without a key

An agent can make its own account with POST /api/v1/accounts, which returns an API key and a claim_url. Give the link to your person: once they open it and sign in with Google, the account’s events move into their Fevori account and the same key works for it. Until then, events stay drafts and invitations can’t be sent. Unclaimed accounts are deleted after 30 days.

Agents can read the same in /auth.md, and how to plan an event well in the Fevori agent skill.

curl https://fevori.app/api/v1/events \
  -H "Authorization: Bearer $FEVORI_API_KEY"

curl https://fevori.app/api/v1/events/EVENT_ID/guests \
  -H "Authorization: Bearer $FEVORI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Alex Rivera", "email": "alex@example.com", "max_party_size": 2}'

A key acts as you, with access to everything your account can see and do, so keep it secret and revoke it on your account page when it’s no longer needed. Invitations go by email; texts are sent only from the event page, where you confirm each guest agreed to get them.

The full description, with every field, is at /api/v1/openapi.json (OpenAPI 3.1). Most tools and agents can read it directly.

Connect an AI assistant (MCP)

Fevori is also an MCP server at https://fevori.app/mcp, so assistants that support the Model Context Protocol can plan events, manage guest lists, check who’s coming and send invitations, with the same rules as everywhere else.

You’ll sign in with Google and choose what the assistant may do: see your events and guest lists (always), change them, and email invitations in your name. You can disconnect it on your account page. Assistants that can’t sign in can send an API key instead, as Authorization: Bearer fev_…; a key can do everything.

Account

POST /api/v1/accounts

Make an agent account. For an AI agent with no key: makes a temporary account and returns its API key (shown once) and a claim_url. Give the claim_url to your person; once they sign in with Google there, the account's events move into theirs and the same key works for their account. Until then, events stay drafts and invitations can't be sent. Unclaimed accounts are deleted after 30 days. A few per minute per IP address. No key needed.

GET /api/v1/me

Who this key acts as. Includes whether the account has been claimed, and its claim_url if not.

GET /api/v1/health

Is the API up. No key needed.

Events

GET /api/v1/events

List your events. Undated events last; otherwise latest start first.

POST /api/v1/events

Create an event. An unclaimed agent account can only make drafts, and at most 25 events.

GET /api/v1/events/{eventId}

Get an event.

PATCH /api/v1/events/{eventId}

Change an event. Send only the fields to change; null clears an optional field. An unclaimed agent account can’t publish.

DELETE /api/v1/events/{eventId}

Delete an event. Also deletes its guests and their invite links. Cannot be undone.

Guests

GET /api/v1/events/{eventId}/guests

List an event's guests. In the order they were added.

POST /api/v1/events/{eventId}/guests

Add a guest. Adds the guest and makes their personal invite link. Nothing is sent.

GET /api/v1/events/{eventId}/guests/{guestId}

Get a guest.

PATCH /api/v1/events/{eventId}/guests/{guestId}

Change a guest. Send only the fields to change. Their invite link stays the same.

DELETE /api/v1/events/{eventId}/guests/{guestId}

Remove a guest. Their invite link stops working. Cannot be undone.

Invitations

POST /api/v1/events/{eventId}/invitations

Email invitations. Queues an invitation email to each guest, with their personal link. Without guest_ids, goes to every guest with an email address who hasn’t been emailed yet; with guest_ids, to those guests, again if already emailed. The event must be published, and the account claimed by a person. Guests with no email, who unsubscribed, or with an email already on its way are skipped.

Errors

Errors come back with an HTTP status and a body like {"error": {"code": "invalid_request", "message": "…", "details": ["…"]}}. Codes: unauthorized (401), account_unclaimed (403, with the claim_url), not_found (404), invalid_json and invalid_request (400), email_taken and event_not_published (409), rate_limited (429) and internal (500).

Questions or problems: support@fevori.app.