AI Scheduling API Tutorial: Build a Long-Running Group-Meeting Workflow

Build the long-running scheduling workflow in eight steps

Start from one durable meeting request. The HTTP request that creates it should return quickly. The coordination job can then wait for calendar reads, participant replies, approvals, and provider recovery without keeping a model call or server thread open.

1. 1

   Parse the instruction into a versioned meeting brief

   Create a record with meeting_request_id, revision, organizer, purpose, duration, date window, booking deadline, meeting time zone, working-hour policy, location, approval mode, and approved outreach channels. Split people into required_participants and optional_participants. Preserve the original instruction for audit, but run the workflow from typed fields.
   • Reject a brief with no organizer, duration, date window, or required participant.
   • Use IANA time-zone names rather than permanent UTC offsets.
   • Bind every later approval and proposal to the current revision.
2. 2

   Create one durable job and return its handle

   Accept the brief through a command such as POST /meeting-requests, persist it before starting work, and return 202 Accepted with the request ID, current state, status URL, and allowed next actions. A worker may crash. A model session may end. Neither event should erase the meeting or force the organizer to repeat the brief.
   • Store state outside the model transcript.
   • Make request creation idempotent for client retries.
   • Expose cancel, revise, approve, and status operations against the same handle.
3. 3

   Resolve consent and availability source per participant

   For each person, record organizer authority, permitted contact channel, calendar connection, consent state, time zone, and role. Read approved Google or Microsoft free/busy when available. Normalize provider results into intervals with participant ID, source, retrieval time, time zone, and error state. Missing or partial evidence is not free time.
   • Ask for the smallest calendar permission that supports free/busy.
   • Keep event titles, descriptions, and attendee lists out of agent context.
   • Separate expired access, denied access, throttling, and provider failure.
4. 4

   Pause for conversational availability without losing state

   Calendar connection is optional. Create an outreach task for an unconnected participant that includes organizer, purpose, duration, bounded date window, time zone, and response deadline. Parse the answer into the same availability shape as connected free/busy. A reply such as ‘Tuesday afternoon’ without a zone moves to needs_clarification; it does not become a guessed interval.
   • Require an approved channel before contacting a participant.
   • Cap reminders and honor decline, opt-out, and do-not-contact state.
   • Silence from a required participant blocks completion rather than changing the quorum.
5. 5

   Wake on events and recompute from current evidence

   Resume the job when a participant replies, a calendar changes, an approval arrives, or a deadline timer fires. Treat notifications as signals to fetch or reconcile current state, not as the full truth. Increment the evidence version when a required calendar, participant response, time zone, or meeting constraint changes. Invalidate proposals built from an older version.
   • Deduplicate every inbound event before changing meeting state.
   • Process out-of-order notifications against provider and meeting versions.
   • Rebuild after an invalid sync token or expired subscription.
6. 6

   Generate slots with deterministic attendance policy

   Intersect every required participant first. Score surviving slots for optional attendance, working hours, organizer preferences, buffers, time-zone fairness, and the booking deadline. Store the evidence version and rejection reason behind each proposal. Let the model explain the tradeoff; keep quorum and consent rules in deterministic code.
   • Never drop a required participant to produce a convenient answer.
   • Show which optional people can attend each proposal.
   • A no-overlap result names the smallest constraints an authorized person could change.
7. 7

   Approve and commit exactly one canonical event

   Bind approval to the meeting revision, proposal ID, attendee set, organizer calendar, and start time. Re-check fresh free/busy immediately before the write. Derive a booking key from that approved tuple, persist the provider event identifier, and reconcile an uncertain timeout before retrying. A repeated tool call must return the original event rather than send a second invitation.
   • Expire approval after a required constraint or calendar changes.
   • Record partial writes as recoverable state instead of claiming success.
   • Keep booking, rescheduling, and cancellation as separate authorized actions.
8. 8

   Return verified completion and meeting-level observability

   Finish only after verifying organizer calendar, event ID, start, end, time zone, required attendees, optional attendees, and invitation dispatch. Emit meeting states such as collecting_availability, waiting_on_required_participant, proposal_ready, awaiting_approval, committing, confirmed, and needs_review.
   • Trace provider calls, participant messages, approvals, and commits by meeting request ID.
   • Alert on stuck states, exhausted retries, and duplicate-commit attempts.
   • Every terminal exception includes evidence and one safe operator action.

Choose an AI scheduling API by the work it owns

Endpoints are not the product boundary. Compare the durable meeting state, external reach, fallback, recovery, and proof behind them.