{"openapi":"3.1.0","info":{"title":"Prezence External API","version":"1.0.0","summary":"API-enabled event platform for your AI agents","description":"Create events, sync guest lists, and generate hostess codes for the Prezence CheckIn app through a machine-to-machine API.","contact":{"name":"Prezence","email":"hello@prezence.app"}},"servers":[{"url":"https://api.prezence.io","description":"Production API"}],"tags":[{"name":"Events","description":"Create and read events in a tenant workspace."},{"name":"Invitations","description":"List and fully synchronize event guest lists."},{"name":"Hostess Codes","description":"Generate staff login codes for the Prezence CheckIn app."}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Use the format: Api-Key pzk_<prefix>_<token>"}},"schemas":{"ErrorResponse":{"type":"object","required":["detail"],"properties":{"detail":{"type":"string","examples":["Invalid API key"]}}},"ValidationErrorResponse":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"examples":[{"invitations":["Duplicate emails found in the invitation list."]}]},"Event":{"type":"object","required":["id","title","description","location","event_date","event_time","event_end_date","event_end_time","capacity","state","is_active","created_at","updated_at"],"properties":{"id":{"type":"integer","examples":[42]},"title":{"type":"string","examples":["Product Launch 2026"]},"description":{"type":"string","examples":["Invite-only launch event."]},"location":{"type":"string","examples":["Convention Center Hall A"]},"event_date":{"type":"string","format":"date","examples":["2026-09-01"]},"event_time":{"type":"string","format":"time","examples":["14:00:00"]},"event_end_date":{"type":["string","null"],"format":"date","examples":["2026-09-01"]},"event_end_time":{"type":["string","null"],"format":"time","examples":["23:00:00"]},"capacity":{"type":["integer","null"],"minimum":1,"examples":[200]},"state":{"type":"string","examples":["launched"]},"is_active":{"type":"boolean","examples":[true]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"EventCreateRequest":{"type":"object","required":["title","event_date","event_time"],"properties":{"title":{"type":"string","maxLength":255,"examples":["Product Launch 2026"]},"event_date":{"type":"string","format":"date","examples":["2026-09-01"]},"event_time":{"type":"string","format":"time","examples":["14:00"]},"event_end_date":{"type":["string","null"],"format":"date"},"event_end_time":{"type":["string","null"],"format":"time"},"location":{"type":"string","maxLength":255,"examples":["Convention Center Hall A"]},"description":{"type":"string"},"capacity":{"type":["integer","null"],"minimum":1,"examples":[200]}}},"Invitation":{"type":"object","required":["id","first_name","last_name","email","rsvp_status","check_in_status","checkin_at","note","plus_guests_allowed","plus_one_guests","tags","external_reference","created_at","updated_at"],"properties":{"id":{"type":"integer","examples":[102]},"first_name":{"type":"string","examples":["Jane"]},"last_name":{"type":"string","examples":["Smith"]},"email":{"type":"string","format":"email","examples":["jane@example.com"]},"rsvp_status":{"type":"string","enum":["pending","confirmed","declined","maybe"]},"check_in_status":{"type":"string","examples":["not_checked_in"]},"checkin_at":{"type":["string","null"],"format":"date-time"},"note":{"type":["string","null"]},"plus_guests_allowed":{"type":"integer","minimum":0},"plus_one_guests":{"type":"array","items":{"$ref":"#/components/schemas/PlusOneGuest"}},"tags":{"type":"array","items":{"type":"string"},"examples":[["VIP","Press"]]},"external_reference":{"type":["string","null"],"maxLength":100,"examples":["crm-guest-123"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"InvitationSyncItem":{"type":"object","required":["first_name","last_name","email"],"properties":{"first_name":{"type":"string","maxLength":100,"examples":["Jane"]},"last_name":{"type":"string","maxLength":100,"examples":["Smith"]},"email":{"type":"string","format":"email","examples":["jane@example.com"]},"rsvp_status":{"type":"string","enum":["pending","confirmed","declined","maybe"],"default":"pending"},"note":{"type":["string","null"]},"plus_guests_allowed":{"type":"integer","minimum":0,"default":0},"auto_create_plus_one_guests":{"type":"boolean","default":false,"description":"When true, Prezence reconciles regular plus-one guest rows to match plus_guests_allowed."},"tags":{"type":"array","items":{"type":"string","maxLength":100}},"external_reference":{"type":["string","null"],"maxLength":100}}},"InvitationSyncRequest":{"type":"object","required":["invitations"],"properties":{"invitations":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/InvitationSyncItem"}}}},"InvitationSyncResponse":{"type":"object","required":["created","updated","removed","total","results"],"properties":{"created":{"type":"integer","examples":[1]},"updated":{"type":"integer","examples":[1]},"removed":{"type":"integer","examples":[0]},"total":{"type":"integer","examples":[2]},"results":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}}}},"PlusOneGuest":{"type":"object","required":["id","first_name","last_name","rsvp_status","check_in_status","is_forced","created_at","updated_at"],"properties":{"id":{"type":"integer"},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"rsvp_status":{"type":"string","enum":["pending","confirmed","declined","maybe"]},"check_in_status":{"type":"string","examples":["pending"]},"is_forced":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"HostessCode":{"type":"object","required":["id","code","expires_at","created_at"],"properties":{"id":{"type":"integer"},"code":{"type":"string","pattern":"^\\d{6}$","examples":["482917"]},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"HostessCodeCreateRequest":{"type":"object","properties":{"num_codes":{"type":"integer","minimum":1,"maximum":50,"default":1},"expires_at":{"type":["string","null"],"format":"date-time","description":"Defaults to 24 hours from creation when omitted."}}},"HostessCodeCreateResponse":{"type":"object","required":["codes"],"properties":{"codes":{"type":"array","items":{"type":"object","required":["code","expires_at"],"properties":{"code":{"type":"string","pattern":"^\\d{6}$","examples":["482917"]},"expires_at":{"type":"string","format":"date-time"}}}}}}},"responses":{"Unauthorized":{"description":"Authentication failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The requested event was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ValidationError":{"description":"Request validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponse"}}}}}},"security":[{"apiKeyAuth":[]}],"paths":{"/api/v2/external/events/":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"List events","description":"Returns all active events for the authenticated tenant, newest event date first.","responses":{"200":{"description":"A list of active events.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Events"],"operationId":"createEvent","summary":"Create an event","description":"Creates a launched event for the tenant. Email sending is disabled for events created through the external API.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventCreateRequest"},"example":{"title":"Product Launch 2026","event_date":"2026-09-01","event_time":"14:00","location":"Convention Center Hall A","capacity":200}}}},"responses":{"201":{"description":"The created event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v2/external/events/{event_id}/":{"get":{"tags":["Events"],"operationId":"getEvent","summary":"Get event detail","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The event.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v2/external/events/{event_id}/invitations/":{"get":{"tags":["Invitations"],"operationId":"listInvitations","summary":"List event invitations","description":"Returns invitations for an event, including both external API and portal-created invitations.","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"external_reference","in":"query","required":false,"schema":{"type":"string"},"description":"Filter invitations by an external system reference."}],"responses":{"200":{"description":"A list of invitations.","content":{"application/json":{"schema":{"type":"object","required":["results","total"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Invitation"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"tags":["Invitations"],"operationId":"syncInvitations","summary":"Full-sync event invitations","description":"Replaces the external guest list for an event. Invitations created by the portal are preserved when omitted from the sync payload.","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationSyncRequest"},"example":{"invitations":[{"first_name":"Jane","last_name":"Smith","email":"jane@example.com","rsvp_status":"confirmed","plus_guests_allowed":2,"auto_create_plus_one_guests":true,"tags":["VIP"],"external_reference":"crm-guest-123"}]}}}},"responses":{"200":{"description":"Sync summary and resulting invitation list.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationSyncResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v2/external/events/{event_id}/hostess-codes/":{"get":{"tags":["Hostess Codes"],"operationId":"listHostessCodes","summary":"List active hostess codes","description":"Returns active, non-expired, unused hostess codes for the event.","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"A list of active hostess codes.","content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/HostessCode"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Hostess Codes"],"operationId":"createHostessCodes","summary":"Generate hostess codes","description":"Generates 1 to 50 six-digit codes that staff can use to open the Prezence CheckIn app for an event.","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostessCodeCreateRequest"},"example":{"num_codes":3,"expires_at":"2026-09-01T23:59:00Z"}}}},"responses":{"201":{"description":"The generated hostess codes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HostessCodeCreateResponse"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}