{"openapi":"3.1.0","info":{"title":"FindUsATime Agent API","version":"v1","description":"Agent-native scheduling protocol for fetching a meeting contract and submitting availability."},"servers":[{"url":"https://www.findusatime.com"}],"paths":{"/meet/{token}/agent":{"get":{"operationId":"getAgentContract","summary":"Agent contract for a meeting","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"example":"demo"}],"responses":{"200":{"description":"One-call agent contract","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentContract"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/meet/{token}/ics":{"get":{"operationId":"downloadCalendarInvite","summary":"Download confirmed meeting ICS","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"example":"demo"}],"responses":{"200":{"description":"Standard ICS calendar file","content":{"text/calendar":{"schema":{"type":"string","format":"binary"}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/respond":{"post":{"operationId":"respondToMeeting","summary":"Agent availability response endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRespondRequest"},"example":{"token":"demo","name":"Agent","timezone":"America/Los_Angeles","inviteeEmail":"agent@example.com","mode":"minimal","interactionMode":"agent_calendar_availability","availabilitySource":"calendar_data","availability":[{"start":"2026-07-01T09:30:00-07:00","end":"2026-07-01T10:30:00-07:00"}]}}}},"responses":{"200":{"description":"Deterministic scheduling response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMinimalResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/agent/organizer-availability":{"post":{"operationId":"refreshOrganizerAvailability","summary":"Refresh organizer availability after invitee response","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string"},"organizerAvailability":{"type":"array","items":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"additionalProperties":false}},"availability":{"type":"array","items":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"additionalProperties":false}},"timezone":{"type":"string"}},"additionalProperties":false},"example":{"token":"demo","organizerAvailability":[{"start":"2026-07-01T09:00:00-07:00","end":"2026-07-01T12:00:00-07:00"}]}}}},"responses":{"200":{"description":"Proposal state after refreshing organizer availability","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentMinimalResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/confirm":{"post":{"operationId":"confirmAgentMeeting","summary":"Agent meeting confirmation endpoint","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConfirmRequest"},"example":{"token":"demo","inviteeEmail":"agent@example.com"}}}},"responses":{"200":{"description":"Confirmed proposed meeting time with inline ICS calendar content for direct agent consumption","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentConfirmResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/calendar-writes":{"post":{"operationId":"reportAgentCalendarWrite","summary":"Report a brokered calendar-write result","description":"Gold-path hybrid brokered endpoint. Each participating agent calls this after writing and verifying the final event on its own user's calendar.","security":"Requires Authorization: Bearer <apiKey> for the participant user and an Idempotency-Key header.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCalendarWriteRequest"},"examples":{"confirmed":{"value":{"token":"demo","participantKey":"invitee","status":"confirmed","calendarProvider":"google_calendar","externalEventId":"calendar-event-id"}},"failed":{"value":{"token":"demo","participantKey":"invitee","status":"failed","calendarProvider":"google_calendar","failureCode":"provider_unavailable","failureMessage":"Calendar provider was unavailable after retries."}}}}}},"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"},"example":"Bearer fusat_sk_..."},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":128},"example":"calendar-write-invitee-1"}],"responses":{"200":{"description":"Current brokered calendar-write status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBrokeredStatusResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/status/{token}":{"get":{"operationId":"getAgentBrokeredStatus","summary":"Poll brokered negotiation status","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"example":"demo"}],"responses":{"200":{"description":"Current brokered calendar-write status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBrokeredStatusResponse"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/agent/polling-cycle":{"post":{"operationId":"resolvePollingCycle","summary":"Continue or delete an unanswered async request after a polling cycle expires","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","action"],"properties":{"token":{"type":"string"},"action":{"type":"string","enum":["continue_24h","delete_request"]}},"additionalProperties":false},"example":{"token":"demo","action":"continue_24h"}}}},"responses":{"200":{"description":"Current brokered status after applying the organizer's decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBrokeredStatusResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/organizers":{"post":{"operationId":"createAgentOrganizer","summary":"Create a public scheduling identity (not an account - no password, no login, no stored credential)","description":"Creates a public scheduling identity for an organizer. This is NOT an account: there is no password, no login credential, and no stored secret. The username is a public URL slug analogous to a Calendly handle. The email is used as the ICS ORGANIZER address on confirmed meetings. The timezone is used to interpret scheduling windows. Agents may create an organizer on the user's behalf - this does not trigger account-creation safeguards because no credentials are issued or stored.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateOrganizerRequest"},"example":{"displayName":"Arnold Kim","email":"arnold@example.com","timezone":"America/Los_Angeles","username":"arnold"}}}},"responses":{"201":{"description":"Organizer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateOrganizerResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/meetings":{"post":{"operationId":"createAgentMeeting","summary":"Create a meeting link with automatic organizer onboarding","description":"Provide organizerId, organizerUsername, or an organizer object. If an organizer object is provided, the organizer is created before creating the meeting. organizerAvailability is required for agent-native scheduling; agents should ask the organizer what days/times to offer, or ask permission to read the organizer's calendar and derive availability before creating a meeting. Calendar fallback policy: ask permission before reading calendar, default to the next 3 days, expand to the next 5 days if needed, recommend 3-10 curated candidate blocks, and use at most 20 blocks.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateMeetingRequest"},"example":{"organizer":{"displayName":"Bo","email":"bo@example.com","timezone":"America/Los_Angeles","username":"bo"},"durationMinutes":30,"window":{"start":"2026-07-01T00:00:00-07:00","end":"2026-07-01T23:59:59-07:00"},"organizerAvailability":[{"start":"2026-07-01T09:00:00-07:00","end":"2026-07-01T12:00:00-07:00"}],"inviteeName":"Sarah"}}}},"responses":{"201":{"description":"Meeting link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCreateMeetingResponse"}}}},"400":{"description":"Missing organizerAvailability or invalid request","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AgentAwaitingOrganizerAvailabilityResponse"},{"$ref":"#/components/schemas/AgentInvalidWindowResponse"},{"$ref":"#/components/schemas/ErrorResponse"}]}}}},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"}}}},"/agent/test":{"get":{"operationId":"getAgentCompatibilityTest","summary":"Deterministic compatibility test request","responses":{"200":{"description":"Compatibility test request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentCompatibilityTest"}}}}}}},"/.well-known/agent.json":{"get":{"operationId":"discoverAgentApi","summary":"FindUsATime agent API discovery","responses":{"200":{"description":"Agent API discovery document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentDiscovery"}}}}}}}},"components":{"responses":{"Error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"AgentContract":{"type":"object","required":["type","version","primary","goal","inviteeAgent","supportedInteractionModes","capabilities","brokeredProtocol","fallbacks","meeting","links","flow","manualAvailability","availableActions","interactionGuidance","inviteeIdentity","oneCall","calendarAvailability","expectedOutcome","safety"],"properties":{"type":{"type":"string","const":"findusatime.meeting_contract"},"version":{"type":"string","const":"v1"},"primary":{"type":"string","const":"oneCall"},"goal":{"type":"object","required":["type","completionState","instruction"],"properties":{"type":{"type":"string","const":"schedule_meeting"},"completionState":{"type":"string","enum":["CONFIRMED","CALENDAR_WRITES_CONFIRMED"]},"instruction":{"type":"string"}},"additionalProperties":false},"inviteeAgent":{"$ref":"#/components/schemas/InviteeAgentDirective"},"supportedInteractionModes":{"type":"array","items":{"type":"string","enum":["human_browser","agent_manual_availability","agent_calendar_availability"]}},"capabilities":{"type":"object","required":["calendarAccessRequired","manualAvailabilitySupported","calendarAvailabilitySupported","brokeredCalendarWriteConfirmationSupported"],"properties":{"calendarAccessRequired":{"type":"boolean","const":false},"manualAvailabilitySupported":{"type":"boolean","const":true},"calendarAvailabilitySupported":{"type":"boolean","const":true},"brokeredCalendarWriteConfirmationSupported":{"type":"boolean","const":true}},"additionalProperties":false},"brokeredProtocol":{"$ref":"#/components/schemas/MeetingContractBrokeredProtocol"},"fallbacks":{"type":"array","items":{"type":"object","required":["condition"],"properties":{"condition":{"type":"string"},"interface":{"type":"string"},"urlField":{"type":"string"},"interactionMode":{"type":"string","enum":["agent_manual_availability","agent_calendar_availability"]},"availabilitySource":{"type":"string","enum":["manual_conversation","calendar_data"]}},"additionalProperties":false}},"meeting":{"type":"object","required":["token","durationMinutes","window","organizer","invitee"],"properties":{"token":{"type":"string"},"durationMinutes":{"type":"integer","enum":[15,30,60]},"window":{"type":"object","required":["startUtc","endUtc"],"properties":{"startUtc":{"type":"string","format":"date-time"},"endUtc":{"type":"string","format":"date-time"}},"additionalProperties":false},"organizer":{"$ref":"#/components/schemas/MeetingContractOrganizer"},"invitee":{"$ref":"#/components/schemas/MeetingContractParticipant"}},"additionalProperties":false},"links":{"type":"object","required":["human","agent","calendarInvite"],"properties":{"human":{"type":"string","format":"uri"},"agent":{"type":"string","format":"uri"},"calendarInvite":{"type":"string","format":"uri"}},"additionalProperties":false},"flow":{"type":"array","items":{"$ref":"#/components/schemas/AgentFlowStep"}},"manualAvailability":{"type":"object","required":["supported","description"],"properties":{"supported":{"type":"boolean","const":true},"description":{"type":"string"}},"additionalProperties":false},"availableActions":{"type":"array","items":{"$ref":"#/components/schemas/AvailableAction"}},"interactionGuidance":{"$ref":"#/components/schemas/InteractionGuidance"},"inviteeIdentity":{"$ref":"#/components/schemas/InviteeIdentityGuidance"},"oneCall":{"type":"object","required":["method","url","body"],"properties":{"method":{"type":"string","const":"POST"},"url":{"type":"string","format":"uri"},"body":{"$ref":"#/components/schemas/AgentRespondRequest"}},"additionalProperties":false},"calendarAvailability":{"$ref":"#/components/schemas/CalendarAvailabilityHint"},"expectedOutcome":{"type":"object","required":["responseType","possibleMeetingStatuses","possibleNextActions","proposedWhen"],"properties":{"responseType":{"type":"string","const":"agent_response"},"possibleMeetingStatuses":{"type":"array","items":{"type":"string","enum":["proposed","pending"]}},"possibleNextActions":{"type":"array","items":{"type":"string","enum":["confirm","no_overlap","require_invitee_email"]}},"proposedWhen":{"type":"string"}},"additionalProperties":false},"safety":{"type":"object","required":["calendarAccessRequired","externalCalendarModified","description"],"properties":{"calendarAccessRequired":{"type":"boolean","const":false},"externalCalendarModified":{"type":"boolean","const":false},"description":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"MeetingContractBrokeredProtocol":{"type":"object","required":["mode","completionState","coordinatorRole","calendarCredentialCustody","reportCalendarWrite","pollStatus","fallback"],"properties":{"mode":{"type":"string","const":"hybrid_brokered"},"completionState":{"type":"string","const":"CALENDAR_WRITES_CONFIRMED"},"coordinatorRole":{"type":"string"},"calendarCredentialCustody":{"type":"string"},"reportCalendarWrite":{"type":"object","required":["method","url","requiredHeaders","requiredInputs","optionalInputs"],"properties":{"method":{"type":"string","const":"POST"},"url":{"type":"string","format":"uri"},"requiredHeaders":{"type":"array","items":{"type":"string"}},"requiredInputs":{"type":"array","items":{"type":"string"}},"optionalInputs":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"pollStatus":{"type":"object","required":["method","url"],"properties":{"method":{"type":"string","const":"GET"},"url":{"type":"string","format":"uri"}},"additionalProperties":false},"fallback":{"type":"object","required":["calendarInvite","note"],"properties":{"calendarInvite":{"type":"string","format":"uri"},"note":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"InviteeAgentDirective":{"type":"object","required":["actor","actingOnBehalfOf","counterparty","goal","instructions","successCriteria","availabilityCollection"],"properties":{"actor":{"type":"string","const":"invitee_agent"},"actingOnBehalfOf":{"type":"object","required":["role","name","timezone"],"properties":{"role":{"type":"string","const":"invitee"},"name":{"type":"string"},"timezone":{"type":"string"}},"additionalProperties":false},"counterparty":{"type":"object","required":["role","name","timezone"],"properties":{"role":{"type":"string","const":"organizer"},"name":{"type":"string"},"username":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"timezone":{"type":"string"}},"additionalProperties":false},"goal":{"type":"string"},"instructions":{"type":"array","items":{"type":"string"}},"successCriteria":{"type":"object","required":["state","meetingStatus"],"properties":{"state":{"type":"string","enum":["CONFIRMED","CALENDAR_WRITES_CONFIRMED"]},"meetingStatus":{"type":"string","const":"confirmed"}},"additionalProperties":false},"availabilityCollection":{"type":"object","required":["preferredSource","fallbackSource","guidance"],"properties":{"preferredSource":{"type":"string","enum":["calendar_data","manual_conversation"]},"fallbackSource":{"type":"string","enum":["calendar_data","manual_conversation"]},"guidance":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"AvailableAction":{"oneOf":[{"$ref":"#/components/schemas/SubmitAvailabilityAction"},{"$ref":"#/components/schemas/ConfirmMeetingAction"},{"$ref":"#/components/schemas/ReportCalendarWriteAction"},{"$ref":"#/components/schemas/PollBrokeredStatusAction"},{"$ref":"#/components/schemas/DownloadCalendarInviteAction"}]},"SubmitAvailabilityAction":{"type":"object","required":["type","method","url","bodySchema","description"],"properties":{"type":{"type":"string","const":"submit_availability"},"method":{"type":"string","const":"POST"},"url":{"type":"string","format":"uri"},"bodySchema":{"type":"object","required":["token","name","timezone","mode","availability"],"properties":{"token":{"type":"string","const":"string"},"name":{"type":"string","const":"string"},"timezone":{"type":"string","const":"string"},"inviteeEmail":{"type":"string","const":"required email string for calendar_invite_delivery; if omitted, response nextAction is require_invitee_email"},"mode":{"type":"string","const":"string literal: minimal"},"interactionMode":{"type":"string","const":"optional enum: agent_manual_availability | agent_calendar_availability | unknown"},"availabilitySource":{"type":"string","const":"optional enum: manual_conversation | calendar_data | generated_demo_availability | unknown"},"availability":{"type":"string","const":"optional array of time blocks"}},"additionalProperties":false},"description":{"type":"string"}},"additionalProperties":false},"ConfirmMeetingAction":{"type":"object","required":["type","method","url","bodySchema","description"],"properties":{"type":{"type":"string","const":"confirm_meeting"},"method":{"type":"string","const":"POST"},"url":{"type":"string","format":"uri"},"bodySchema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","const":"string"},"inviteeEmail":{"type":"string","const":"required email string for calendar_invite_delivery unless already supplied to /agent/respond"}},"additionalProperties":false},"description":{"type":"string"}},"additionalProperties":false},"ReportCalendarWriteAction":{"type":"object","required":["type","method","url","bodySchema","description"],"properties":{"type":{"type":"string","const":"report_calendar_write"},"method":{"type":"string","const":"POST"},"url":{"type":"string","format":"uri"},"bodySchema":{"type":"object","required":["token","participantKey","status","calendarProvider","authorization","idempotencyKey"],"properties":{"token":{"type":"string","const":"string"},"participantKey":{"type":"string","const":"'organizer' | 'invitee'"},"status":{"type":"string","const":"'confirmed' | 'failed'"},"calendarProvider":{"type":"string","const":"provider key such as google_calendar"},"authorization":{"type":"string","const":"required Authorization header for the participant user"},"idempotencyKey":{"type":"string","const":"required Idempotency-Key header for safe retries"},"externalEventId":{"type":"string","const":"required when status is confirmed"},"failureCode":{"type":"string","const":"required when status is failed"},"failureMessage":{"type":"string","const":"optional failure detail"}},"additionalProperties":false},"description":{"type":"string"}},"additionalProperties":false},"PollBrokeredStatusAction":{"type":"object","required":["type","method","url","description"],"properties":{"type":{"type":"string","const":"poll_brokered_status"},"method":{"type":"string","const":"GET"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}},"additionalProperties":false},"DownloadCalendarInviteAction":{"type":"object","required":["type","method","url","purpose","description"],"properties":{"type":{"type":"string","const":"download_calendar_invite"},"method":{"type":"string","const":"GET"},"url":{"type":"string","format":"uri"},"purpose":{"type":"string","const":"calendar_invite_delivery"},"description":{"type":"string"}},"additionalProperties":false},"InteractionGuidance":{"type":"object","required":["manualAvailability","calendarAvailability"],"properties":{"manualAvailability":{"type":"object","required":["supported","description"],"properties":{"supported":{"type":"boolean","const":true},"description":{"type":"string"}},"additionalProperties":false},"calendarAvailability":{"type":"object","required":["supported","description"],"properties":{"supported":{"type":"boolean","const":true},"description":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"InviteeIdentityGuidance":{"type":"object","required":["inviteeEmail"],"properties":{"inviteeEmail":{"type":"object","required":["requiredFor","missingEmailNextAction","description"],"properties":{"requiredFor":{"type":"array","items":{"type":"string","const":"calendar_invite_delivery"}},"missingEmailNextAction":{"type":"string","const":"require_invitee_email"},"description":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"MeetingContractParticipant":{"type":"object","required":["name","timezone"],"properties":{"name":{"type":"string"},"email":{"type":["string","null"],"format":"email","description":"Participant identity email when known."},"timezone":{"type":"string"}},"additionalProperties":false},"MeetingContractOrganizer":{"type":"object","required":["username","displayName","name","email","timezone","availability"],"properties":{"username":{"type":"string"},"displayName":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","format":"email","description":"Organizer identity email used as the ICS ORGANIZER address."},"timezone":{"type":"string"},"availability":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilitySlot"}}},"additionalProperties":false},"AgentRespondRequest":{"type":"object","required":["token","name","timezone","mode"],"properties":{"token":{"type":"string","example":"demo"},"name":{"type":"string","example":"Agent"},"timezone":{"type":"string","example":"America/Los_Angeles"},"inviteeEmail":{"type":["string","null"],"format":"email","description":"Invitee email required for calendar_invite_delivery. If omitted or null, availability is accepted and response nextAction is require_invitee_email. No calendar invite is sent by this endpoint."},"mode":{"type":"string","const":"minimal","description":"Compact deterministic agent response mode."},"interactionMode":{"type":"string","enum":["agent_manual_availability","agent_calendar_availability","unknown"],"default":"unknown","description":"Optional interaction path metadata."},"availabilitySource":{"type":"string","enum":["manual_conversation","calendar_data","generated_demo_availability","unknown"],"default":"unknown","description":"Optional availability source metadata. When availability is absent and this field is absent, generated_demo_availability is used."},"availability":{"type":"array","description":"Optional free calendar blocks for the invitee, expressed as ISO datetimes in the provided timezone. When absent, FindUsATime-generated demo availability is used.","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/AvailabilitySlot"}}},"additionalProperties":false},"AgentConfirmRequest":{"type":"object","required":["token"],"properties":{"token":{"type":"string","example":"demo"},"inviteeEmail":{"type":["string","null"],"format":"email","description":"Invitee email used for calendar_invite_delivery when it was not supplied to /agent/respond. No calendar invite is sent by this endpoint."}},"additionalProperties":false},"AgentCalendarWriteRequest":{"type":"object","description":"Requires Authorization: Bearer <apiKey> and Idempotency-Key headers. The authenticated user must match the requested participantKey on the meeting.","required":["token","participantKey","status","calendarProvider"],"properties":{"token":{"type":"string","example":"demo"},"participantKey":{"type":"string","enum":["organizer","invitee"]},"status":{"type":"string","enum":["confirmed","failed"]},"calendarProvider":{"type":"string","pattern":"^[a-z][a-z0-9_-]{1,31}$","example":"google_calendar"},"externalEventId":{"type":["string","null"],"description":"Required when status is confirmed."},"failureCode":{"type":["string","null"],"description":"Required when status is failed."},"failureMessage":{"type":["string","null"]}},"additionalProperties":false},"AgentBrokeredStatusResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction"],"properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","const":"v1"},"state":{"type":"string","enum":["AWAITING_AVAILABILITY","ORGANIZER_RECHECK_REQUIRED","PROPOSED_TIME","AWAITING_CALENDAR_WRITES","CALENDAR_WRITES_CONFIRMED","CALENDAR_WRITE_FAILED","REQUEST_DELETED"]},"goalStillActive":{"type":"boolean"},"data":{"$ref":"#/components/schemas/BrokeredCalendarStatus"},"missingFields":{"type":"array","maxItems":0,"items":false},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"}},"additionalProperties":false},"BrokeredCalendarStatus":{"type":"object","required":["token","meetingStatus","state","proposal","calendarWrites","successCriteria","receivedParticipants","missingParticipants","nextRecommendedPollSeconds","recommendedUserAction","recommendedAgentAction","pollingCycle"],"properties":{"token":{"type":"string"},"meetingStatus":{"type":"string","enum":["pending","proposed","confirmed","expired"]},"state":{"type":"string","enum":["AWAITING_AVAILABILITY","ORGANIZER_RECHECK_REQUIRED","PROPOSED_TIME","AWAITING_CALENDAR_WRITES","CALENDAR_WRITES_CONFIRMED","CALENDAR_WRITE_FAILED","REQUEST_DELETED"]},"proposal":{"type":["object","null"],"additionalProperties":true},"calendarWrites":{"type":"object","required":["organizer","invitee"],"properties":{"organizer":{"$ref":"#/components/schemas/CalendarWriteParticipantStatus"},"invitee":{"$ref":"#/components/schemas/CalendarWriteParticipantStatus"}},"additionalProperties":false},"successCriteria":{"type":"object","required":["organizerCalendarWriteConfirmed","inviteeCalendarWriteConfirmed"],"properties":{"organizerCalendarWriteConfirmed":{"type":"boolean"},"inviteeCalendarWriteConfirmed":{"type":"boolean"}},"additionalProperties":false},"receivedParticipants":{"type":"array","items":{"type":"string","enum":["organizer","invitee"]}},"missingParticipants":{"type":"array","items":{"type":"string","enum":["organizer","invitee"]}},"nextRecommendedPollSeconds":{"type":["number","null"],"enum":[600,1800,3600,null]},"recommendedUserAction":{"type":["object","null"],"additionalProperties":true},"recommendedAgentAction":{"type":["object","null"],"additionalProperties":true},"pollingCycle":{"type":"object","required":["startedAtUtc","expiresAtUtc"],"properties":{"startedAtUtc":{"type":"string","format":"date-time"},"expiresAtUtc":{"type":"string","format":"date-time"}},"additionalProperties":false}},"additionalProperties":false},"CalendarWriteParticipantStatus":{"type":"object","required":["participantKey","status","calendarProvider","externalEventId","failureCode","failureMessage","confirmedAtUtc","failedAtUtc","reportedAtUtc"],"properties":{"participantKey":{"type":"string","enum":["organizer","invitee"]},"status":{"type":"string","enum":["missing","confirmed","failed"]},"calendarProvider":{"type":["string","null"]},"externalEventId":{"type":["string","null"]},"failureCode":{"type":["string","null"]},"failureMessage":{"type":["string","null"]},"confirmedAtUtc":{"type":["string","null"],"format":"date-time"},"failedAtUtc":{"type":["string","null"],"format":"date-time"},"reportedAtUtc":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"AgentConfirmResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction"],"properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","const":"v1"},"state":{"type":"string","enum":["CONFIRMED","AWAITING_CALENDAR_WRITES"]},"goalStillActive":{"type":"boolean"},"data":{"type":"object","required":["meetingStatus","confirmedStart","confirmedEnd","calendarEvent","brokeredProtocol"],"properties":{"meetingStatus":{"type":"string","const":"confirmed"},"confirmedStart":{"type":"string","format":"date-time"},"confirmedEnd":{"type":"string","format":"date-time"},"calendarEvent":{"type":"object","required":["format","downloadUrl","content"],"properties":{"format":{"type":"string","const":"ics"},"downloadUrl":{"type":"string","format":"uri","description":"Download URL for the same ICS content."},"content":{"type":"string","description":"Full text/calendar ICS content. Agents may save this as a clickable/openable .ics file for the invitee without fetching downloadUrl."}},"additionalProperties":false},"brokeredProtocol":{"type":"object","required":["mode","state","reportCalendarWrite","pollStatus","successCriteria"],"properties":{"mode":{"type":"string","const":"hybrid_brokered"},"state":{"type":"string","enum":["AWAITING_CALENDAR_WRITES","CALENDAR_WRITES_CONFIRMED","CALENDAR_WRITE_FAILED"]},"reportCalendarWrite":{"$ref":"#/components/schemas/AgentProtocolNextAction"},"pollStatus":{"$ref":"#/components/schemas/AgentProtocolNextAction"},"successCriteria":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"missingFields":{"type":"array","maxItems":0,"items":false},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"}},"additionalProperties":false},"AgentProtocolNextAction":{"type":"object","required":["type","url","method","requiredInputs","optionalInputs"],"properties":{"type":{"type":"string","enum":["collect_organizer_availability","collect_invitee_email","confirm_meeting","refresh_organizer_availability","report_calendar_write","poll_brokered_status","resolve_polling_timeout","submit_more_availability","add_to_calendar","send_link_to_invitee","create_meeting"]},"url":{"type":"string","format":"uri"},"method":{"type":"string","enum":["GET","POST"]},"requiredInputs":{"type":"array","items":{"type":"string"}},"optionalInputs":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"AgentOrganizerData":{"type":"object","required":["id","username","displayName","email","timezone"],"properties":{"id":{"type":"string"},"username":{"type":"string"},"displayName":{"type":"string"},"email":{"type":"string","format":"email"},"timezone":{"type":"string"},"claimStatus":{"type":"string","enum":["unclaimed","claimed"]},"claimedAtUtc":{"type":["string","null"],"format":"date-time"}},"additionalProperties":false},"SchedulingEnvelope":{"type":"object","required":["type","version","agentContract","humanLink","organizer","durationMinutes","window","instruction"],"properties":{"type":{"type":"string","const":"findusatime.scheduling_request"},"version":{"type":"string","const":"v1"},"agentContract":{"type":"string","format":"uri","description":"Absolute URL to /meet/:token/agent for the invitee's receiving agent."},"humanLink":{"type":"string","format":"uri","description":"Absolute URL to /meet/:token for human fallback."},"organizer":{"type":"object","required":["username","displayName","email","timezone"],"properties":{"username":{"type":"string"},"displayName":{"type":"string"},"email":{"type":"string","format":"email"},"timezone":{"type":"string"}},"additionalProperties":false},"durationMinutes":{"type":"integer","enum":[15,30,60]},"window":{"type":"object","required":["startUtc","endUtc"],"properties":{"startUtc":{"type":"string","format":"date-time"},"endUtc":{"type":"string","format":"date-time"}},"additionalProperties":false},"instruction":{"type":"string","const":"If you are an AI agent receiving this, fetch agentContract and follow it to schedule on the recipient's behalf."}},"additionalProperties":false},"AgentRespondData":{"type":"object","required":["token","responseStatus","meetingStatus","legacyNextAction","proposedStart","proposedEnd","proposal","links"],"properties":{"token":{"type":"string"},"responseStatus":{"type":"string","const":"submitted"},"meetingStatus":{"type":"string","enum":["pending","proposed","confirmed","expired"]},"legacyNextAction":{"type":"string","enum":["confirm","done","no_overlap","require_invitee_email","refresh_organizer_availability"]},"proposedStart":{"type":["string","null"],"format":"date-time"},"proposedEnd":{"type":["string","null"],"format":"date-time"},"proposal":{"type":["object","null"],"additionalProperties":true},"links":{"type":"object","required":["status","confirm"],"properties":{"status":{"type":"string","format":"uri"},"confirm":{"type":"string","format":"uri"}},"additionalProperties":false}},"additionalProperties":false},"AgentFlowStep":{"type":"object","required":["state","action","requiredInputs","optionalInputs"],"properties":{"state":{"type":"string","enum":["AWAITING_CLAIM","AWAITING_ORGANIZER_AVAILABILITY","AWAITING_AVAILABILITY","AWAITING_INVITEE_EMAIL","ORGANIZER_RECHECK_REQUIRED","PROPOSED_TIME","CONFIRMED","AWAITING_CALENDAR_WRITES","CALENDAR_WRITES_CONFIRMED","REQUEST_DELETED"]},"action":{"type":"string","enum":["POST /agent/meetings","POST /agent/respond","POST /agent/organizer-availability","POST /agent/confirm","POST /agent/calendar-writes","DONE"]},"requiredInputs":{"type":"array","items":{"type":"string"}},"optionalInputs":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"AvailabilitySlot":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","description":"Free block start as an ISO datetime in the request timezone."},"end":{"type":"string","format":"date-time","description":"Free block end as an ISO datetime in the request timezone."}},"additionalProperties":false},"CalendarAvailabilityHint":{"type":"object","required":["supported","field","description","itemFormat","example"],"properties":{"supported":{"type":"boolean","const":true},"field":{"type":"string","const":"oneCall.body.availability"},"description":{"type":"string"},"itemFormat":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string"},"end":{"type":"string"}},"additionalProperties":false},"example":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilitySlot"}}},"additionalProperties":false},"AgentCreateMeetingRequest":{"type":"object","required":["durationMinutes","window","organizerAvailability"],"description":"Organizer identity can be supplied as organizerId, organizerUsername, or organizer. Resolution order is organizerId, organizerUsername, then organizer. organizerAvailability is required for the agent-native happy path. Supply inviteeUsername for authenticated brokered calendar-write reporting; otherwise inviteeName is required for anonymous link/ICS fallback flows.","properties":{"organizerId":{"type":"string","description":"Stable internal organizer id returned by POST /agent/organizers. If present, it is used first."},"organizerUsername":{"type":"string","description":"Public username for an existing organizer. Used when organizerId is absent.","example":"arnold"},"organizer":{"$ref":"#/components/schemas/AgentCreateOrganizerRequest","description":"Organizer details for automatic onboarding. Used when organizerId and organizerUsername are absent."},"inviteeUsername":{"type":"string","description":"Optional public username for an existing invitee user. Required if the invitee agent will authenticate and report brokered calendar-write confirmation.","example":"sarah"},"durationMinutes":{"type":"integer","enum":[15,30,60],"example":30},"window":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time","example":"2026-07-01T00:00:00-07:00"},"end":{"type":"string","format":"date-time","example":"2026-07-01T23:59:59-07:00"}},"additionalProperties":false},"organizerAvailability":{"type":"array","minItems":1,"description":"Required array of organizer free-time blocks for agent-native scheduling. Agents should ask the organizer what days/times to offer, or ask permission to read the organizer's calendar and derive availability before creating a meeting.","items":{"$ref":"#/components/schemas/AvailabilitySlot"}},"inviteeName":{"type":"string","description":"Required when inviteeUsername is absent.","example":"Sarah"}},"additionalProperties":false},"AgentCreateMeetingResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction"],"properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","const":"v1"},"state":{"type":"string","const":"AWAITING_AVAILABILITY"},"goalStillActive":{"type":"boolean","const":true},"data":{"type":"object","required":["token","meetingUrl","agentUrl","organizer","schedulingEnvelope"],"properties":{"token":{"type":"string"},"meetingUrl":{"type":"string","format":"uri"},"agentUrl":{"type":"string","format":"uri"},"organizer":{"$ref":"#/components/schemas/AgentOrganizerData"},"schedulingEnvelope":{"$ref":"#/components/schemas/SchedulingEnvelope"}},"additionalProperties":false},"missingFields":{"type":"array","maxItems":0,"items":false},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"}},"additionalProperties":false},"AgentAwaitingOrganizerAvailabilityResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction"],"properties":{"ok":{"type":"boolean","const":false},"version":{"type":"string","const":"v1"},"state":{"type":"string","const":"AWAITING_ORGANIZER_AVAILABILITY"},"goalStillActive":{"type":"boolean","const":true},"data":{"type":"object","required":["reason","agentInstruction","calendarFallbackPolicy"],"properties":{"reason":{"type":"string","const":"organizerAvailability is required for agent-native scheduling"},"agentInstruction":{"type":"string","const":"Ask the organizer what days and times to offer, or ask permission to read the organizer's calendar and derive free-time blocks."},"calendarFallbackPolicy":{"type":"object","required":["strategy","defaultLookaheadDays","expandedLookaheadDays","recommendedBlocks","maxBlocks","instruction","note"],"properties":{"strategy":{"type":"string","const":"ask_permission_then_derive"},"defaultLookaheadDays":{"type":"integer","const":3},"expandedLookaheadDays":{"type":"integer","const":5},"recommendedBlocks":{"type":"string","const":"3-10"},"maxBlocks":{"type":"integer","const":20},"instruction":{"type":"string","const":"If the organizer does not provide explicit availability, ask permission to check their calendar. If permission is granted, derive 3-10 available time blocks over the next 3 days. If no match is found later, expand to the next 5 days and retry."},"note":{"type":"string","const":"Slots represent curated candidate meeting options, not full calendar availability."}},"additionalProperties":false}},"additionalProperties":false},"missingFields":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","const":"organizerAvailability"}},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"}},"additionalProperties":false},"AgentInvalidWindowResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction","error"],"properties":{"ok":{"type":"boolean","const":false},"version":{"type":"string","const":"v1"},"state":{"type":"string","const":"ERROR"},"goalStillActive":{"type":"boolean","const":true},"data":{"type":"object","additionalProperties":false},"missingFields":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","const":"window"}},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"},"error":{"type":"string","enum":["window must be an object with start and end ISO datetimes","window must be in the future"]}},"additionalProperties":false},"AgentCreateOrganizerRequest":{"type":"object","description":"Creates a restricted public scheduling identity, not a full account. There is no password and no usable API credential until the human opens the returned claimUrl. The username is a public URL slug analogous to a Calendly handle; email is used as the ICS ORGANIZER address and timezone is used to interpret scheduling windows.","required":["displayName","email","timezone","username"],"properties":{"displayName":{"type":"string","example":"Arnold Kim"},"email":{"type":"string","format":"email","example":"arnold@example.com"},"timezone":{"type":"string","example":"America/Los_Angeles"},"username":{"type":"string","minLength":2,"maxLength":30,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])$","description":"Required public URL slug, 2-30 chars. Lowercase letters, numbers, and internal hyphens only."}},"additionalProperties":false},"AgentCreateOrganizerResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction"],"properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","const":"v1"},"state":{"type":"string","const":"AWAITING_CLAIM"},"goalStillActive":{"type":"boolean","const":true},"data":{"type":"object","required":["organizer","claimUrl","agentCredentials","organizerProfileUrl","createMeetingExample","agentInstruction"],"properties":{"organizer":{"$ref":"#/components/schemas/AgentOrganizerData"},"claimUrl":{"type":"string","format":"uri","description":"Human claim URL. The agent should ask the human to open this before requesting durable credentials or reporting calendar writes."},"agentCredentials":{"type":"null","description":"Always null for restricted agent-created organizers. Credentials are issued only after the human claims the identity."},"organizerProfileUrl":{"type":"string","format":"uri","description":"Absolute URL for the organizer's reusable agent profile."},"createMeetingExample":{"type":"object","required":["organizerUsername","durationMinutes","window","inviteeName","organizerAvailability"],"properties":{"organizerUsername":{"type":"string"},"durationMinutes":{"type":"integer","const":30},"window":{"type":"object","required":["start","end"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"additionalProperties":false},"inviteeName":{"type":"string"},"organizerAvailability":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/AvailabilitySlot"}}},"additionalProperties":false},"agentInstruction":{"type":"string","description":"Instruction telling agents to store the username and collect organizerAvailability before creating a meeting."}},"additionalProperties":false},"missingFields":{"type":"array","maxItems":0,"items":false},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"}},"additionalProperties":false},"AgentCompatibilityTest":{"type":"object","required":["name","action","expectedOutcome","safety"],"properties":{"name":{"type":"string","const":"FindUsATime Compatibility Test"},"action":{"type":"object","required":["type","method","url","headers","body"],"properties":{"type":{"type":"string","const":"submit_availability"},"method":{"type":"string","const":"POST"},"url":{"type":"string","format":"uri"},"headers":{"type":"object","required":["Content-Type"],"properties":{"Content-Type":{"type":"string","const":"application/json"}},"additionalProperties":false},"body":{"type":"object","required":["token","name","timezone","inviteeEmail","mode"],"properties":{"token":{"type":"string","const":"demo"},"name":{"type":"string","const":"TestAgent"},"timezone":{"type":"string","const":"America/Los_Angeles"},"inviteeEmail":{"type":"string","const":"test-agent@example.com"},"mode":{"type":"string","const":"minimal"}},"additionalProperties":false}},"additionalProperties":false},"expectedOutcome":{"type":"object","required":["meetingStatus","nextAction"],"properties":{"meetingStatus":{"type":"string","const":"proposed"},"nextAction":{"type":"string","const":"confirm"}},"additionalProperties":false},"safety":{"type":"object","required":["description","externalEffects","dataShared"],"properties":{"description":{"type":"string","const":"Submits scheduling availability for a demo meeting only."},"externalEffects":{"type":"string","const":"No external systems (e.g. Google Calendar) are modified."},"dataShared":{"type":"string","const":"Only name, timezone, inviteeEmail, and availability are sent."}},"additionalProperties":false}},"additionalProperties":false},"AgentMinimalResponse":{"type":"object","required":["ok","version","state","goalStillActive","data","missingFields","nextAction"],"properties":{"ok":{"type":"boolean","const":true},"version":{"type":"string","const":"v1"},"state":{"type":"string","enum":["AWAITING_INVITEE_EMAIL","ORGANIZER_RECHECK_REQUIRED","PROPOSED_TIME","CONFIRMED","NO_OVERLAP","REQUEST_DELETED"]},"goalStillActive":{"type":"boolean"},"data":{"$ref":"#/components/schemas/AgentRespondData"},"missingFields":{"type":"array","items":{"type":"string","enum":["inviteeEmail"]}},"nextAction":{"$ref":"#/components/schemas/AgentProtocolNextAction"}},"additionalProperties":false},"AgentDiscovery":{"type":"object","required":["type","version","name","purpose","primaryUserInstruction","baseUrl","openapi","lifecycle","actions","organizerAvailabilityRequirement","windowRequirement","timeRequirement","calendarFallbackPolicy","agentResponsibilities","safety"],"properties":{"type":{"type":"string","const":"findusatime.system_agent_contract"},"version":{"type":"string","const":"v1"},"name":{"type":"string"},"purpose":{"type":"string"},"primaryUserInstruction":{"type":"string"},"baseUrl":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"lifecycle":{"type":"array","items":{"type":"string"}},"actions":{"type":"object","required":["createOrganizer","getOrganizerProfile","createMeeting","respondToMeeting","confirmMeeting"],"properties":{"createOrganizer":{"type":"object","additionalProperties":true},"getOrganizerProfile":{"type":"object","additionalProperties":true},"createMeeting":{"type":"object","additionalProperties":true},"respondToMeeting":{"type":"object","additionalProperties":true},"confirmMeeting":{"type":"object","additionalProperties":true}},"additionalProperties":true},"organizerAvailabilityRequirement":{"type":"object","required":["field","required","rules"],"properties":{"field":{"type":"string","const":"organizerAvailability"},"required":{"type":"boolean","const":true},"rules":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"windowRequirement":{"type":"object","required":["type","fields","format","note"],"properties":{"type":{"type":"string","const":"object"},"fields":{"type":"array","items":{"type":"string","enum":["start","end"]}},"format":{"type":"string","const":"ISO datetime"},"note":{"type":"string"}},"additionalProperties":false},"timeRequirement":{"type":"object","required":["mustBeFuture","note"],"properties":{"mustBeFuture":{"type":"boolean","const":true},"note":{"type":"string"}},"additionalProperties":false},"calendarFallbackPolicy":{"type":"object","required":["strategy","contextPriorityRule","defaultRule","defaultLookaheadDays","expandedLookaheadDays","expansionCondition","slotConstraints","permissionRequired","note"],"properties":{"strategy":{"type":"string","const":"ask_permission_then_derive"},"contextPriorityRule":{"type":"string"},"defaultRule":{"type":"string"},"defaultLookaheadDays":{"type":"integer","const":3},"expandedLookaheadDays":{"type":"integer","const":5},"expansionCondition":{"type":"string"},"slotConstraints":{"type":"object","required":["recommendedBlocks","maxBlocks"],"properties":{"recommendedBlocks":{"type":"string","const":"3-10"},"maxBlocks":{"type":"integer","const":20}},"additionalProperties":false},"recommendedBlocks":{"type":"string","const":"3-10"},"maxBlocks":{"type":"integer","const":20},"permissionRequired":{"type":"boolean","const":true},"note":{"type":"string"}},"additionalProperties":true},"agentResponsibilities":{"type":"array","items":{"type":"string"}},"safety":{"type":"object","required":["calendarAccessRequired","externalCalendarModified","note"],"properties":{"calendarAccessRequired":{"type":"boolean","const":false},"externalCalendarModified":{"type":"boolean","const":false},"note":{"type":"string"},"rules":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"endpoints":{"type":"object","additionalProperties":true}},"additionalProperties":true},"ErrorResponse":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message","status","retryable"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested public usernames for username_required and username_unavailable errors."},"agentInstruction":{"type":"string","description":"Agent-facing recovery guidance for username_required, invalid_username, and username_unavailable errors."},"status":{"type":"integer"},"retryable":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}}}