# Calendar Sync API > 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. Canonical page: https://venuewiki.net/developers/calendar-api OpenAPI 3.1: https://venuewiki.net/developers/calendar-api/openapi.json ## Machine readable The HTML page is https://venuewiki.net/developers/calendar-api. The OpenAPI 3.1 document is https://venuewiki.net/developers/calendar-api/openapi.json. The plain text for coding tools is https://venuewiki.net/developers/calendar-api/llms.txt. All three are built from the route list, the error catalogue and the limits in the Calendar Sync code. If a number here disagrees with that code, the code wins. ## What this is 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. It is the company side of Calendar Sync. It is not the venue API, and it is not a crew plan. A company admin creates a key, then your system pushes crew and shifts. I write an event on a person's calendar only when they have switched your company on and they are allowed Calendar Sync. When that switch is on, I also share their busy times with you. GET /api/cal/availability returns start and end only. No titles or details. Base URL: https://venuewiki.net Push on every change. The hourly pass is a backstop. It is not a sync from your system. | Method | Path | Scope | State | | --- | --- | --- | --- | | GET | /api/cal/me | cal:me:read | Open | | POST | /api/cal/shifts | cal:shifts:write | Open | | PUT | /api/cal/crew | cal:crew:write | Open | | GET | /api/cal/availability | cal:availability:read | Open | | PUT | /api/cal/callback | cal:callback:write | Coming soon | ## Create a key A company admin creates the key on the company page, in the Custom integrations card. The address ends with #custom-integrations. I check companies.adminUids. Site admin is not required, and it is not a bypass. The card uses a signed-in session. A Calendar Sync key cannot create, rotate or revoke keys. Give the key a name, 1 to 100 characters. The card offers expiry of 30, 90 or 365 days, or never. The request field is expiresInDays: an integer from 1 to 365, or null for never. If you leave it out, I use 90 days. I show the full key once, in the browser, after the sign-in check succeeds. I store only a hash. I will not show it again. Copy it then. A working key is vwc_live_, then 16 characters, then an underscore, then 43 characters. In every example I write vwc_live_XXXX. That is not a working key. After creation I list a prefix, the first 12 characters, not the secret. A company can have 5 active keys. A key still inside its rotation grace counts. This company already has 5 active keys. Revoke one first. Rotate issues a new key for the same company and shows it once. The previous key keeps working for 24 hours, then it stops. If you leave expiry out on rotate, a key that does not expire stays that way. A key that does expire is replaced with a new 90 day key unless you send expiresInDays. Revoke stops the key immediately. 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. Create, rotate and revoke all need that fresh sign-in. The window is 10 minutes. An IP allow list is optional, up to 20 entries. Each entry is an IPv4 address, an IPv4 prefix, or one IPv6 address. Leave it blank to allow any address. I email every company admin when a key is created, and when one is rotated, because rotation creates a key. The email names the key and who created it. It never contains the key. Revoke does not send that email. The card calls signed-in routes: GET and POST /api/companies/{companyId}/cal-keys, POST /api/companies/{companyId}/cal-keys/{keyId}/rotate, and DELETE /api/companies/{companyId}/cal-keys/{keyId}. A Calendar Sync key is rejected on those routes. ## Authentication Send the company key on every data request: Authorization: Bearer vwc_live_XXXX The key is bound to one company. Do not send a company id in the path, the query or the body. If you send one and it is a different company, I reject the request with 403 company_mismatch. I use the company stored on the key. Every key has these scopes, and only these: cal:me:read, cal:shifts:write, cal:crew:write, cal:availability:read, cal:callback:write. You cannot choose a subset. You cannot add a venue API scope, an MCP scope, or an admin scope. The key works only on the routes in the table above. A venue API key or an MCP token is rejected here. This key is rejected on every other route, including the venue API. There is no normal product rate limit. The only ceiling is 6000 requests a minute for one key, to stop a leaked key or a runaway loop. Over that I return 429 and Too many Calendar Sync requests. Wait a minute and try again. ## Errors Errors use one shape. requestId is on Calendar Sync route errors. Cache-Control is no-store. I also send X-Request-Id. A batch that fails validation, or that is over the cap, stores nothing and cancels nothing. | HTTP | Code | Where | Meaning | | --- | --- | --- | --- | | 401 | missing_or_malformed_key | Calendar Sync routes | The Authorization header is missing, or it is not a Calendar Sync key. Send Authorization: Bearer vwc_live_XXXX. | | 401 | invalid_key | Calendar Sync routes | The key is not recognised, or the secret does not match. | | 401 | key_revoked | Calendar Sync routes | The key was revoked. It stops immediately. | | 401 | key_expired | Calendar Sync routes | The key has expired. A key whose rotation grace has ended is expired too. | | 401 | ip_not_allowed | Calendar Sync routes | The key has an IP allow list and this address is not on it. A blank allow list means any address. | | 401 | route_not_allowed | Any other /api/cal path | That path is not part of Calendar Sync. A valid key is still denied. | | 401 | unauthenticated | Key management, and a key used off the allowlist | 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. | | 403 | company_mismatch | Calendar Sync routes and key management | The request named a different company from the key, or from the company page. | | 403 | insufficient_scope | Calendar Sync routes | The key does not have the scope for that route. A key from the card has every Calendar Sync scope. | | 403 | reauth_required | Create, rotate or revoke a key | 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. | | 403 | forbidden | Key management | Only a company admin can manage keys for this company. | | 429 | rate_limited | Calendar Sync routes | 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. | | 400 | validation_failed | Shifts, crew, availability and key management | A field is missing or not usable. On a shift or crew push, nothing from that request was stored, and nothing was cancelled. | | 400 | too_many_keys | Create a key | This company already has 5 active keys. Revoke one first. | | 404 | not_found | Rotate or revoke | That key is not on this company. | | 501 | not_implemented | PUT /api/cal/callback | Callback setup is not available yet. A push callback is coming soon. Read busy times with GET /api/cal/availability. | | 413 | payload_too_large | Shifts and crew | 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. | | 500 | internal | Calendar Sync routes | I could not finish the request. On a shift push, nothing was cancelled. | ### Error ```json { "error": { "code": "validation_failed", "message": "Shift 2 needs an email address.", "requestId": "req_example" } } ``` ### Over the batch cap ```json { "error": { "code": "payload_too_large", "message": "A shift push can include at most 500 shifts. Split the push and send the rest in another request.", "requestId": "req_example" } } ``` ## GET /api/cal/me Who the key belongs to. The company comes from the key, not from the query. companyName is null when the company has no name stored. expiresAt is null when the key does not expire. graceUntil is set only while a rotated key is still inside its grace. ### curl ```bash curl -sS -X GET https://venuewiki.net/api/cal/me \ -H "Authorization: Bearer vwc_live_XXXX" ``` ### JavaScript fetch ```javascript const response = await fetch("https://venuewiki.net/api/cal/me", { method: "GET", headers: { Authorization: "Bearer vwc_live_XXXX", }, }); const data = await response.json(); ``` ### Response ```json { "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 } ``` ## POST /api/cal/shifts Send one shift, or a batch. Use the same id again to update. Set status to cancelled to remove that shift. A top-level JSON array is a batch with full left false. 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 in one request. Over that, the response is 413 and nothing is stored. A shift push can include at most 500 shifts. Split the push and send the rest in another request. full false, or omitted on a batch, updates only the shifts you sent. full true means this list is every shift that should remain. One shift on its own cannot be a full push. Do not send a single shift and a shifts array together. On a full push I cancel stored shifts whose start is inside the last 30 days or the next 730 days, when those shifts are missing from the list. Shifts older than that stay as they are. If the JSON is invalid, or the batch is over the cap, I cancel nothing. The same id twice in one push is rejected. I store nothing from that request. accepted is how many shifts I stored. removed is how many I cancelled because they were missing from a full push. calendar counts what I did for people who are matched, switched on, entitled and connected. skipped means the event was already right. incomplete means I stopped early and did not remove events I had not read. | Field | Required | Notes | | --- | --- | --- | | id | yes | Your id for this shift. 1 to 200 characters. It starts with a letter or number, then letters, numbers, and . _ : @ + -. A whole number is stored as text. | | email | yes for confirmed | The address your roster uses. I trim it and lowercase it. A cancelled shift can omit it. | | start, end | yes | ISO date and time, or a date only (2026-12-01) for an all-day shift. Both have to be dates, or both times. The end has to be after the start. For an all-day shift, send the end as the day after the last day. A one day shift on 1 December 2026 uses start 2026-12-01 and end 2026-12-02. | | timezone | yes, unless all-day | IANA name, for example Australia/Sydney. UTC is accepted. I reject a name I do not recognise. An all-day shift does not need one. | | title | no | Shown on the calendar. Empty becomes Shift. Longer than 500 characters is rejected. | | location | no | Shown on the event. Longer than 500 characters is cut. A location change updates the calendar event. | | status | no | confirmed (default) or cancelled. | | full | batch only | true or false. Omitted means false. Not allowed on a single shift. | ### curl, one shift ```bash curl -sS -X POST https://venuewiki.net/api/cal/shifts \ -H "Authorization: Bearer vwc_live_XXXX" \ -H "Content-Type: application/json" \ -d '{"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"}' ``` ### JavaScript fetch, one shift ```javascript const response = await fetch("https://venuewiki.net/api/cal/shifts", { method: "POST", headers: { Authorization: "Bearer vwc_live_XXXX", "Content-Type": "application/json", }, body: JSON.stringify({"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"}), }); const data = await response.json(); ``` ### curl, batch ```bash curl -sS -X POST https://venuewiki.net/api/cal/shifts \ -H "Authorization: Bearer vwc_live_XXXX" \ -H "Content-Type: application/json" \ -d '{"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"}]}' ``` ### JavaScript fetch, batch ```javascript const response = await fetch("https://venuewiki.net/api/cal/shifts", { method: "POST", headers: { Authorization: "Bearer vwc_live_XXXX", "Content-Type": "application/json", }, body: JSON.stringify({"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"}]}), }); const data = await response.json(); ``` ### curl, cancel ```bash curl -sS -X POST https://venuewiki.net/api/cal/shifts \ -H "Authorization: Bearer vwc_live_XXXX" \ -H "Content-Type: application/json" \ -d '{"id":"job-100","start":"2026-12-01T09:00:00+11:00","end":"2026-12-01T17:00:00+11:00","timezone":"Australia/Sydney","status":"cancelled"}' ``` ### JavaScript fetch, cancel ```javascript const response = await fetch("https://venuewiki.net/api/cal/shifts", { method: "POST", headers: { Authorization: "Bearer vwc_live_XXXX", "Content-Type": "application/json", }, body: JSON.stringify({"id":"job-100","start":"2026-12-01T09:00:00+11:00","end":"2026-12-01T17:00:00+11:00","timezone":"Australia/Sydney","status":"cancelled"}), }); const data = await response.json(); ``` ### Response ```json { "companyId": "your-company", "accepted": 1, "removed": 0, "full": false, "calendar": { "created": 0, "updated": 0, "cancelled": 0, "skipped": 0, "incomplete": false } } ``` ## Idempotency Sending the same id again is safe. A change to start, end or title updates the event. status cancelled removes it. I keep one stored shift for each of your ids, under your company. Pushing that id again replaces the stored shift. It does not create a second one. If start, end and title are unchanged, I leave the calendar event alone. If you change start, end or title, I remove the old event and create a new one, with a short change history on the new event. Each change and each cancel is recorded for that person. status cancelled removes the event. Leaving a shift out of a later full push, when its start is inside the window above, does the same. A push that fails validation does not cancel anything. ## PUT /api/cal/crew Replaces the company's active crew list. This list is everyone who should stay active. People you leave out, or send with active false, are marked inactive. Their switch is left as they set it. They stop receiving new events. Events already on the calendar stay there. An empty list marks every existing person inactive. At most 500 people in the array, including people you mark inactive. A crew push can include at most 500 people. Split the push and send the rest in another request. totalCrew is the active people I stored. matchedCount is how many of those match a VenueWiki account. deactivated is how many previously active people this list left out. calendar is the same counts as a shift push. | Field | Required | Notes | | --- | --- | --- | | id | yes | Your crew id. Same rules as a shift id, up to 200 characters. | | email | yes, unless active is false | I trim it and lowercase it. It has to include @. A person with no email is rejected. | | name | no | Shown as the display name. displayName is accepted too. Longer than 200 characters is cut. | | active | no | true or false. Omitted means active. false marks an existing person inactive and does not need an email. | ### curl ```bash curl -sS -X PUT https://venuewiki.net/api/cal/crew \ -H "Authorization: Bearer vwc_live_XXXX" \ -H "Content-Type: application/json" \ -d '{"crew":[{"id":"42","email":"alex@example.com","name":"Alex","active":true}]}' ``` ### JavaScript fetch ```javascript const response = await fetch("https://venuewiki.net/api/cal/crew", { method: "PUT", headers: { Authorization: "Bearer vwc_live_XXXX", "Content-Type": "application/json", }, body: JSON.stringify({"crew":[{"id":"42","email":"alex@example.com","name":"Alex","active":true}]}), }); const data = await response.json(); ``` ### Response ```json { "companyId": "your-company", "totalCrew": 1, "matchedCount": 0, "deactivated": 0, "calendar": { "created": 0, "updated": 0, "cancelled": 0, "skipped": 0, "incomplete": false } } ``` ## How I match crew I 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. I match by email only, never by name. I trim the address and lowercase it. The login email on VenueWiki wins. If nobody signs in with that address, I use a verified match email, and only when exactly one account holds it. On a crew list, a verified match email is used only when that person has no login email link in this company. An unmatched email is stored. That person stays hidden. They do not appear on the Calendar Sync page, and they do not receive events. If they later sign up with that email, or add it as a verified match email, I link them. A new link starts switched off. They still have to switch the company on. A shift can name an email before you send a crew list. I store the same kind of match row for that address, so a later signup can link it. ## When I write an event Crew only receive events. They do not call this API. This API is free for AV suppliers. I do not charge the company to push. I write an event only when all of these are true. The email matches a VenueWiki account for this company. That person has switched this company on. They are allowed Calendar Sync: AAA Membership, including its 90-day trial. A free-for-life grant, an admin account, or an entitlement override also allows it. They have a calendar connected. Until then I store the shift and write no event. The company appears on their Calendar Sync page, under Custom integrations, only after the match. It stays hidden otherwise. The switch starts off. The switch key is custom- plus the company id, so it cannot clash with another integration. Switching the company on also shares their busy times with you. No titles or details. Switching the company off stops new writes and stops those busy times. Events already on the calendar stay there. They can pick a colour for the company on that page. A signed-in person can also switch it with POST /api/calendar/toggle. That route takes their session, not a Calendar Sync key. ### Switch the company on ```json { "companyId": "custom-your-company", "enabled": true } ``` ## GET /api/cal/availability Read busy times for people who have switched your company on. from and to are required. They are ISO 8601 with a timezone, for example 2026-12-01T09:00:00+11:00. The window can be at most 31 days. from can be no more than 24 hours before now. Pass crew to ask for one person. Use the crew id you sent, or their email. Leave crew out to read everyone in scope. I only return people with a confirmed match in this company, the switch on, Calendar Sync allowed (the same rules as a shift write, including the 90-day trial), and a calendar connected. Anyone else is left out. Each block is a start, an end, and allDay. I never return a title, a description, a location, attendees or an event id. Times are UTC, clipped to the window. allDay is true when the block comes only from all-day events that sit fully inside the window. Overlapping and touching blocks are merged. I leave out events I wrote for your company. That uses the shift id I stored when I created the event. A shift you pushed does not come back as busy time. Events I wrote for another company, and events from another integration, do count as busy. I also leave out events tagged #me or #mine, events that contain the exclusion tag for your company (other companies still receive those), events in a colour or Outlook category that person has excluded, events they declined, and events marked free. A repeating series comes back as its occurrences, not as one master block. status ok with an empty busy list means I read the calendar and they are free in that window. status unknown means I could not read that calendar. Treat unknown as unavailable. One broken calendar does not fail the request. I keep a server cache of 60 seconds so a burst of polls does not hammer the calendar. The HTTP response is not cached. The cache stores start and end only. There is no push of busy times. PUT /api/cal/callback still answers 501. Ask for a window with this route when you need it. | Parameter | Required | Notes | | --- | --- | --- | | from | yes | ISO 8601 with a timezone. No more than 24 hours before now. | | to | yes | After from. The window can be at most 31 days. | | crew | no | One crew id, or one email. Leave it out for everyone in scope. | ### curl ```bash curl -sS -X GET https://venuewiki.net/api/cal/availability?from=2026-12-01T00:00:00Z&to=2026-12-08T00:00:00Z \ -H "Authorization: Bearer vwc_live_XXXX" ``` ### JavaScript fetch ```javascript const response = await fetch("https://venuewiki.net/api/cal/availability?from=2026-12-01T00:00:00Z&to=2026-12-08T00:00:00Z", { method: "GET", headers: { Authorization: "Bearer vwc_live_XXXX", }, }); const data = await response.json(); ``` ### Response ```json { "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" } ] } ``` ## PUT /api/cal/callback Coming soon. The route is on the allowlist, so a valid key is accepted, and then I answer 501 not_implemented. Callback setup is not available yet. A push of busy times to a URL you host is not open. Read busy times with GET /api/cal/availability. ### curl ```bash curl -sS -X PUT https://venuewiki.net/api/cal/callback \ -H "Authorization: Bearer vwc_live_XXXX" \ -H "Content-Type: application/json" \ -d '{"url":"https://example.com/venuewiki"}' ``` ### JavaScript fetch ```javascript const response = await fetch("https://venuewiki.net/api/cal/callback", { method: "PUT", headers: { Authorization: "Bearer vwc_live_XXXX", "Content-Type": "application/json", }, body: JSON.stringify({"url":"https://example.com/venuewiki"}), }); const data = await response.json(); ``` ### Response ```json { "error": { "code": "not_implemented", "message": "Callback setup is not available yet.", "requestId": "req_example" } } ``` ## Push every change Push on every change. The hourly pass is a backstop. It is not a sync from your system. Send a shift when it is created, when it changes, and when it is cancelled. Send the crew list when the roster changes. I do not pull those from your system. About once an hour I reapply the shifts I already store: new events, changes, and cancels. A run that stops early does not remove events it did not read. You do not call that pass. It is not a Calendar Sync key. ## Quiet roster alert A company admin can set "Alert me if no push for X days" on the company manage page, under Custom integrations. X is a whole number from 1 to 30. If it has never been saved, VenueWiki uses 7. The last push is the later of a shift push and a crew push. The card shows that time in Australia/Sydney, and a warning when it is older than the saved number of days. A company that has never pushed stays neutral. VenueWiki does not email anyone in that case. Once a day, VenueWiki emails that company's admins if a push has been quiet for longer than the saved number. Each admin is emailed once per quiet spell. A rejected address is tried again on a later run, up to 3 times, and does not stop the other admins. A new push clears the spell, so the next quiet spell can email again. No-backfill rule: an email is sent only when the moment the quiet spell crosses the threshold is after `stalePushArmedAt`. That time is stored on the first successful push after this alert is in place, and the daily check also stores it when a company is still inside the window and has not been armed yet. A company that has never pushed, or whose quiet spell had already crossed the threshold before VenueWiki was watching, is not emailed on the first run. Saving a shorter number does not create that armed time by itself.