Public developer documentation · API v1

One calendar. Shared with your team.

Read and manage full Google calendars or independent native calendars with your own GFAVIP identity. Every account follows the same calendar permissions.

Read SKILL.md Full API reference (.md)Roadmap

Send these links to a teammate or assistant. The documentation is public; calendar data requires authentication and explicit access.

Get connected

For the calendar owner

Sign in with GFAVIP, then open Calendars.
Choose Add calendar → Find my Google calendars. Connect Google first if needed, then select the calendar you want to share. You can also create a native calendar.
After your teammate has signed in or called the API once, open Sharing and add their exact GFAVIP username as Editor to let them manage events, or Viewer for read access.

For a headless client

Obtain your own GFAVIP Wallet session token through your existing headless sign-in flow.
Call GET /api/v1/calendars with Authorization: Bearer <gfavip_session_token>. The first valid call registers your account here.
An empty calendars list means authentication worked but no calendars are available yet. Ask the owner to share, then call again.

Sharing includes all event details visible to the connected Google account, including personal/private events and events created outside Structure Cal. Each Google calendar must be selected and shared explicitly. Google credentials stay on the server.

Use a Wallet session token

The API validates each bearer token with https://wallet.gfavip.com/api/auth/validate and maps it to a stable GFAVIP user ID. A token identifies you; calendar membership determines what you can do.

For an existing PowerLobster integration, exchange its identity token at Wallet’s POST /api/auth/powerlobster with JSON {"token":"<identity_token>"}. Use the returned sso_token for Structure Cal, and respect expires_at. A PowerLobster API key or Google access token cannot be used directly as the calendar bearer token.

Keep credentials in your client’s secret store. Do not put tokens in URLs, shared messages, or event descriptions. Reauthenticate when a session expires.

Start with your calendars

For a compact morning agenda, use GET /api/v1/calendars/{id}/agenda?tz=Asia/Bangkok. Add date=YYYY-MM-DD for another day. You can also combine selected calendars, preview duplicates, and inspect change history with guarded undo. The API reference describes each endpoint and its limits.

Base URL: https://cal.structure.info/api/v1. Load GFAVIP_SESSION_TOKEN securely into your environment before running this example.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $GFAVIP_SESSION_TOKEN" \
  https://cal.structure.info/api/v1/calendars

Use the returned local calendar id in event requests. Supply timezone-aware time_min and time_max values and follow next_page_token to read the full result.

Method	Path (after /api/v1)	Purpose
GET	`/calendars`	Calendars you can access and your effective role
GET	`/calendars/{id}/events`	Full event list for a date range, including non-booking events
GET	`/calendars/{id}/events/{event_id}`	Current event and its version (`etag`)
POST	`/calendars/{id}/events`	Create an event with an `Idempotency-Key`
PATCH / DELETE	`/calendars/{id}/events/{event_id}`	Edit, move or delete using the current `If-Match` version
GET	`/calendars/{id}/busy`	Busy intervals for a date range

Read the full reference for request/response examples, calendar creation, sharing, pagination, errors and retry rules.

Make changes reliably

Create once: use a unique idempotency key for each intended event and reuse it with the same payload when retrying.
Read before editing: send the exact returned etag, including its quotes, in If-Match. A 412 means something changed; reread before deciding what to do.
Choose notifications: every event write requires send_updates: "none" or "all". Native event changes use "none"; invitations and reminders have separate explicit controls.
Reschedule bookings: Editors can read bookings through the booking API. The owner can enable delegated rescheduling under Calendars → Import, export & calendar preferences → Owner preferences on their primary Google calendar. Editors can check a slot while delegation is off using a preview marked not applicable. Every move requires an applicable preview and explicit notification choice. A separate owner preference allows Editors/Admins to override availability for one booking with a reason. Every preview lists the checks being overridden; real conflicts require a separate explicit flag. Generic event edits remain blocked to keep booking details and reminders consistent.

Google calendars support recurring creation, whole-series edits and previewed future splits. Linked single events can be updated as a group or previewed for conversion into an equivalent series. Event reminders, explicit attendee updates and delegated calendar RSVP are documented in the API guide. Native calendars support recurrence, invitations, import/export and opt-in notifications. Automatic native-to-Google synchronization remains unsupported. See the API reference for exact limits.