{"openapi":"3.1.0","info":{"title":"VenueWiki Calendar Sync API","version":"1","summary":"I built this so a claimed AV company can push its own roster into Calendar Sync. It is free for AV suppliers. Crew only receive events.","description":"I built this so a claimed AV company can push its own roster into Calendar Sync. It is free for AV suppliers. Crew only receive events.\n\nPush on every change. The hourly pass is a backstop. It is not a sync from your system.\n\nSending the same id again is safe. A change to start, end or title updates the event. status cancelled removes it.\n\nI match crew by email. The login email wins. A verified match email is used only when that person has no login email link in this company. An unmatched person stays hidden until they sign up.\n\nCrew switch the company on, and they need AAA Membership, including its 90-day trial. This API is free for AV suppliers. Crew only receive events. Busy times are a pull on GET /api/cal/availability. Start and end only. The callback is coming soon.\n\nBatch cap: 500. Abuse ceiling: 6000 requests a minute for one key.\n\nExample key: vwc_live_XXXX. That is not a working key.\n\nHTML: https://venuewiki.net/developers/calendar-api\n\nPlain text: https://venuewiki.net/developers/calendar-api/llms.txt"},"servers":[{"url":"https://venuewiki.net"}],"tags":[{"name":"Calendar Sync","description":"Push a company roster into Calendar Sync."}],"paths":{"/api/cal/me":{"get":{"tags":["Calendar Sync"],"security":[{"calKey":[]}],"operationId":"getCalMe","summary":"Who this key belongs to","description":"The company comes from the key.","responses":{"200":{"description":"The key and its company.","content":{"application/json":{"schema":{"type":"object","required":["companyId","companyName","keyId","name","prefix","scopes","expiresAt","graceUntil"],"properties":{"companyId":{"type":"string"},"companyName":{"type":["string","null"]},"keyId":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["cal:me:read","cal:shifts:write","cal:crew:write","cal:availability:read","cal:callback:write"]}},"expiresAt":{"type":["string","null"],"format":"date-time"},"graceUntil":{"type":["string","null"],"format":"date-time"}}},"example":{"companyId":"your-company","companyName":"Example Lighting","keyId":"key-id","name":"Roster","prefix":"vwc_live_XXX","scopes":["cal:me:read","cal:shifts:write","cal:crew:write","cal:availability:read","cal:callback:write"],"expiresAt":null,"graceUntil":null}}}},"401":{"description":"missing_or_malformed_key, invalid_key, key_revoked, key_expired, ip_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"company_mismatch, insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait. The ceiling is 6000 requests a minute for one key.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cal/shifts":{"post":{"tags":["Calendar Sync"],"security":[{"calKey":[]}],"operationId":"postCalShifts","summary":"Push one shift or a batch","description":"Sending the same id again is safe. A change to start, end or title updates the event. status cancelled removes it. At most 500 shifts. A shift push can include at most 500 shifts. Split the push and send the rest in another request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Shift"},{"$ref":"#/components/schemas/ShiftBatch"},{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Shift"}}]},"examples":{"one":{"summary":"One shift","value":{"id":"job-100","email":"alex@example.com","start":"2026-12-01T09:00:00+11:00","end":"2026-12-01T17:00:00+11:00","timezone":"Australia/Sydney","title":"Load in","location":"Opera House","status":"confirmed"}},"batch":{"summary":"Batch","value":{"full":false,"shifts":[{"id":"job-100","email":"alex@example.com","start":"2026-12-01T09:00:00+11:00","end":"2026-12-01T17:00:00+11:00","timezone":"Australia/Sydney","title":"Load in","location":"Opera House","status":"confirmed"}]}},"cancel":{"summary":"Cancel","value":{"id":"job-100","start":"2026-12-01T09:00:00+11:00","end":"2026-12-01T17:00:00+11:00","timezone":"Australia/Sydney","status":"cancelled"}}}}}},"responses":{"200":{"description":"Stored. Calendar counts are for people who can receive events.","content":{"application/json":{"schema":{"type":"object","required":["companyId","accepted","removed","full","calendar"],"properties":{"companyId":{"type":"string"},"accepted":{"type":"integer"},"removed":{"type":"integer"},"full":{"type":"boolean"},"calendar":{"type":"object","required":["created","updated","cancelled","skipped","incomplete"],"properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"cancelled":{"type":"integer"},"skipped":{"type":"integer"},"incomplete":{"type":"boolean"}}}}},"example":{"companyId":"your-company","accepted":1,"removed":0,"full":false,"calendar":{"created":0,"updated":0,"cancelled":0,"skipped":0,"incomplete":false}}}}},"400":{"description":"validation_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_or_malformed_key, invalid_key, key_revoked, key_expired, ip_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"company_mismatch, insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait. The ceiling is 6000 requests a minute for one key.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cal/crew":{"put":{"tags":["Calendar Sync"],"security":[{"calKey":[]}],"operationId":"putCalCrew","summary":"Replace the crew list","description":"Match is by email. At most 500 people. A crew push can include at most 500 people. Split the push and send the rest in another request.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrewPush"},"example":{"crew":[{"id":"42","email":"alex@example.com","name":"Alex","active":true}]}}}},"responses":{"200":{"description":"Stored. Unmatched people stay hidden.","content":{"application/json":{"schema":{"type":"object","required":["companyId","totalCrew","matchedCount","deactivated","calendar"],"properties":{"companyId":{"type":"string"},"totalCrew":{"type":"integer"},"matchedCount":{"type":"integer"},"deactivated":{"type":"integer"},"calendar":{"type":"object","required":["created","updated","cancelled","skipped","incomplete"],"properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"cancelled":{"type":"integer"},"skipped":{"type":"integer"},"incomplete":{"type":"boolean"}}}}},"example":{"companyId":"your-company","totalCrew":1,"matchedCount":0,"deactivated":0,"calendar":{"created":0,"updated":0,"cancelled":0,"skipped":0,"incomplete":false}}}}},"400":{"description":"validation_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_or_malformed_key, invalid_key, key_revoked, key_expired, ip_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"company_mismatch, insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"payload_too_large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait. The ceiling is 6000 requests a minute for one key.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cal/availability":{"get":{"tags":["Calendar Sync"],"security":[{"calKey":[]}],"operationId":"getCalAvailability","summary":"Read busy times","description":"Busy blocks for crew who have switched this company on. Start and end only. The window can be at most 31 days. from can be no more than 24 hours before now. A push callback is not this route.","parameters":[{"name":"from","in":"query","required":true,"description":"ISO 8601 with a timezone. No more than 24 hours before now.","schema":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00Z"]}},{"name":"to","in":"query","required":true,"description":"ISO 8601 with a timezone, after from. The window can be at most 31 days.","schema":{"type":"string","format":"date-time","examples":["2026-12-08T00:00:00Z"]}},{"name":"crew","in":"query","required":false,"description":"One crew id, or one email. Leave it out for everyone in scope.","schema":{"type":"string"}}],"responses":{"200":{"description":"Busy times. status unknown means treat that person as unavailable.","content":{"application/json":{"schema":{"type":"object","required":["companyId","from","to","crew"],"properties":{"companyId":{"type":"string"},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"crew":{"type":"array","items":{"$ref":"#/components/schemas/AvailabilityCrew"}}}},"example":{"companyId":"your-company","from":"2026-12-01T00:00:00.000Z","to":"2026-12-08T00:00:00.000Z","crew":[{"id":"42","email":"alex@example.com","status":"ok","busy":[{"start":"2026-12-02T01:00:00.000Z","end":"2026-12-02T05:00:00.000Z","allDay":false}]},{"id":"43","email":"sam@example.com","status":"unknown"}]}}}},"400":{"description":"validation_failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"missing_or_malformed_key, invalid_key, key_revoked, key_expired, ip_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"company_mismatch, insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait. The ceiling is 6000 requests a minute for one key.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/cal/callback":{"put":{"tags":["Calendar Sync"],"security":[{"calKey":[]}],"operationId":"putCalCallback","summary":"Callback setup, coming soon","description":"Coming soon. Callback setup is not available yet. Read busy times with GET /api/cal/availability.","responses":{"401":{"description":"missing_or_malformed_key, invalid_key, key_revoked, key_expired, ip_not_allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"company_mismatch, insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait. The ceiling is 6000 requests a minute for one key.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"internal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"501":{"description":"not_implemented","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"calKey":{"type":"http","scheme":"bearer","bearerFormat":"vwc_live_","description":"Calendar Sync key. Example: Bearer vwc_live_XXXX"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string","enum":["missing_or_malformed_key","invalid_key","key_revoked","key_expired","ip_not_allowed","route_not_allowed","unauthenticated","company_mismatch","insufficient_scope","reauth_required","forbidden","rate_limited","validation_failed","too_many_keys","not_found","not_implemented","payload_too_large","internal"]},"message":{"type":"string"},"requestId":{"type":"string","examples":["req_example"]}}}},"description":"missing_or_malformed_key (401): The Authorization header is missing, or it is not a Calendar Sync key. Send Authorization: Bearer vwc_live_XXXX. invalid_key (401): The key is not recognised, or the secret does not match. key_revoked (401): The key was revoked. It stops immediately. key_expired (401): The key has expired. A key whose rotation grace has ended is expired too. ip_not_allowed (401): The key has an IP allow list and this address is not on it. A blank allow list means any address. route_not_allowed (401): That path is not part of Calendar Sync. A valid key is still denied. unauthenticated (401): Sign in to manage keys. A Calendar Sync key cannot create, rotate or revoke keys. Used on any route outside the allowlist, the key is rejected before the handler runs. company_mismatch (403): The request named a different company from the key, or from the company page. insufficient_scope (403): The key does not have the scope for that route. A key from the card has every Calendar Sync scope. reauth_required (403): Sign in again, then try once more. I need a sign-in from the last 10 minutes before I create, rotate or revoke a key. forbidden (403): Only a company admin can manage keys for this company. rate_limited (429): Too many Calendar Sync requests. Wait a minute and try again. The abuse ceiling is 6000 requests a minute for one key. I also send Retry-After. This is not a normal product limit. validation_failed (400): A field is missing or not usable. On a shift or crew push, nothing from that request was stored, and nothing was cancelled. too_many_keys (400): This company already has 5 active keys. Revoke one first. not_found (404): That key is not on this company. not_implemented (501): Callback setup is not available yet. A push callback is coming soon. Read busy times with GET /api/cal/availability. payload_too_large (413): The batch is over 500. A shift push can include at most 500 shifts. Split the push and send the rest in another request. A crew push can include at most 500 people. Split the push and send the rest in another request. Nothing was stored. internal (500): I could not finish the request. On a shift push, nothing was cancelled."},"Shift":{"type":"object","required":["id","start","end"],"properties":{"id":{"description":"Your id. 1 to 200 characters, starting with a letter or number. A whole number is stored as text.","anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$"},{"type":"integer"}]},"email":{"type":"string","description":"Required when status is confirmed or omitted. Trimmed and lowercased."},"start":{"type":"string","description":"ISO date and time, or a date only for an all-day shift."},"end":{"type":"string","description":"After start. For an all-day shift, the day after the last day."},"timezone":{"type":"string","description":"IANA name. Required unless the shift is all-day. UTC is accepted."},"title":{"type":"string","maxLength":500,"description":"Empty becomes Shift."},"location":{"type":"string","description":"Cut to 500 characters. A location change updates the calendar event."},"status":{"type":"string","enum":["confirmed","cancelled"],"description":"Omitted means confirmed."}}},"ShiftBatch":{"type":"object","required":["shifts"],"properties":{"shifts":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Shift"}},"full":{"type":"boolean","description":"True means this list is every shift that should remain. Omitted means false."}}},"CrewMember":{"type":"object","required":["id"],"properties":{"id":{"description":"Your id. 1 to 200 characters, starting with a letter or number. A whole number is stored as text.","anyOf":[{"type":"string","minLength":1,"maxLength":200,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:@+-]{0,199}$"},{"type":"integer"}]},"email":{"type":"string","description":"Required unless active is false. Must include @."},"name":{"type":"string","description":"Cut to 200 characters."},"displayName":{"type":"string","description":"Cut to 200 characters."},"active":{"type":"boolean","description":"Omitted means true."}}},"CrewPush":{"type":"object","required":["crew"],"properties":{"crew":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/CrewMember"}}}},"BusyBlock":{"type":"object","additionalProperties":false,"required":["start","end","allDay"],"properties":{"start":{"type":"string","format":"date-time","description":"UTC start, clipped to the window."},"end":{"type":"string","format":"date-time","description":"UTC end, clipped to the window."},"allDay":{"type":"boolean","description":"True when the block comes only from all-day events that sit fully inside the window."}}},"AvailabilityCrew":{"type":"object","additionalProperties":false,"required":["id","email","status"],"properties":{"id":{"type":"string","description":"The crew id you sent."},"email":{"type":"string","description":"The email you sent for this person."},"status":{"type":"string","enum":["ok","unknown"],"description":"unknown means the calendar could not be read. Treat that person as unavailable."},"busy":{"type":"array","description":"Present when status is ok. Empty means free in the window. Omitted when status is unknown.","items":{"$ref":"#/components/schemas/BusyBlock"}}}}}}}