{"openapi":"3.1.0","info":{"title":"VenueDB API","version":"1.0.0","description":"Read leads and events, and create leads, for your own company. Authenticate with an API key created in Settings → API."},"servers":[{"url":"/api/v1","description":"Your VenueDB deployment"}],"paths":{"/leads":{"get":{"operationId":"listLeads","summary":"List leads","description":"Returns your company's leads, newest first, one page at a time.","tags":["Leads"],"scope":"read:leads","parameters":[{"name":"limit","in":"query","description":"Page size. Default 25, maximum 100.","schema":{"type":"integer","example":25}},{"name":"cursor","in":"query","description":"The `nextCursor` value from the previous page. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of leads.","schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LeadSummary"}},"nextCursor":{"type":"string","nullable":true,"description":"Pass as `cursor` to get the next page. `null` when there are no more."}}},"example":{"data":[{"id":"cm1x9k2…","status":"NEW","firstName":"Jordan","lastName":"Blake","email":"jordan.blake@example.com","phone":"843-555-0142","eventType":"wedding","eventDate":"2027-05-15T21:00:00.000Z","guestCount":140,"source":"web_form","createdAt":"2026-10-06T14:02:11.000Z"}],"nextCursor":"cm1x9k2…"}},"401":{"description":"Missing, invalid, revoked or expired API key.","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or expired API key"}},"403":{"description":"The key does not have the `read:leads` scope.","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API key is missing scope: read:leads"}},"429":{"description":"Rate limit exceeded (100 requests per minute per key).","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded"}}}},"post":{"operationId":"createLead","summary":"Create a lead","description":"Creates a lead in your company's first active pipeline stage and records it in the lead's history. The lead's source is set to `api`. Note: this does not fire the `lead.created` webhook.","tags":["Leads"],"scope":"write:leads","requestBody":{"required":true,"schema":{"$ref":"#/components/schemas/LeadInput"},"example":{"firstName":"Jordan","lastName":"Blake","email":"jordan.blake@example.com","phone":"843-555-0142","eventType":"wedding","eventDate":"2027-05-15T21:00:00Z","guestCount":140,"notes":"Found us through the website form."}},"responses":{"201":{"description":"The lead was created.","schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"}}}},"400":{"description":"The body is not valid JSON or fails validation. `details` lists the offending fields.","schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"error":"Invalid request body","details":{"formErrors":[],"fieldErrors":{"email":["Invalid email"]}}}},"401":{"description":"Missing, invalid, revoked or expired API key.","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or expired API key"}},"403":{"description":"The key does not have the `write:leads` scope.","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API key is missing scope: write:leads"}},"429":{"description":"Rate limit exceeded (100 requests per minute per key).","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded"}}}}},"/events":{"get":{"operationId":"listEvents","summary":"List events","description":"Returns your company's events ordered by event date, latest first, one page at a time. Time, room and guest count come from the event's first function.","tags":["Events"],"scope":"read:events","parameters":[{"name":"limit","in":"query","description":"Page size. Default 25, maximum 100.","schema":{"type":"integer","example":25}},{"name":"cursor","in":"query","description":"The `nextCursor` value from the previous page. Omit for the first page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of events.","schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventSummary"}},"nextCursor":{"type":"string","nullable":true}}},"example":{"data":[{"id":"ev_0042","status":"CONFIRMED","eventName":"Bennett–Sutton Wedding","eventType":"wedding","eventDate":"2027-05-15T21:30:00.000Z","venueId":"cm1…","clientId":"cl_0042","createdAt":"2026-02-03T15:20:00.000Z","startTime":"2027-05-15T21:30:00.000Z","endTime":"2027-05-16T03:00:00.000Z","eventSpaceId":"cm1…","guestCount":220}],"nextCursor":null}},"401":{"description":"Missing, invalid, revoked or expired API key.","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or expired API key"}},"403":{"description":"The key does not have the `read:events` scope.","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API key is missing scope: read:events"}},"429":{"description":"Rate limit exceeded (100 requests per minute per key).","schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded"}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"ValidationError":{"type":"object","properties":{"error":{"type":"string"},"details":{"type":"object","description":"Zod `flatten()` output: `formErrors` and a `fieldErrors` map of field → messages."}}},"LeadSummary":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","description":"A value from your company's lead stages (e.g. `NEW`, `CONTACTED`, `QUOTE_SENT`). Stages are configurable in Settings → Custom Lists."},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true,"description":"A value from your Event Types list, e.g. `wedding`."},"eventDate":{"type":"string","format":"date-time","nullable":true},"guestCount":{"type":"integer","nullable":true},"source":{"type":"string","nullable":true,"description":"e.g. `web_form`, `referral`, `api`."},"createdAt":{"type":"string","format":"date-time"}}},"Lead":{"type":"object","description":"A full lead record as stored. Fields not listed here may be added over time.","properties":{"id":{"type":"string"},"companyId":{"type":"string"},"venueId":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"status":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"eventDate":{"type":"string","format":"date-time","nullable":true},"eventType":{"type":"string","nullable":true},"guestCount":{"type":"integer","nullable":true},"source":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"LeadInput":{"type":"object","required":["firstName","lastName"],"properties":{"firstName":{"type":"string","description":"Required."},"lastName":{"type":"string","description":"Required."},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"eventDate":{"type":"string","format":"date-time","description":"ISO 8601 with a time zone, e.g. `2027-05-15T21:00:00Z`."},"eventType":{"type":"string","description":"Free text; use one of your Event Types values (e.g. `wedding`) so it filters and reports correctly."},"guestCount":{"type":"integer","description":"Positive whole number."},"notes":{"type":"string"}}},"EventSummary":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["INQUIRY","HOLD","TENTATIVE","CONFIRMED","COMPLETED","CANCELED","NO_SHOW"]},"eventName":{"type":"string","nullable":true},"eventType":{"type":"string","nullable":true},"eventDate":{"type":"string","format":"date-time","description":"Start of the event's earliest function."},"venueId":{"type":"string"},"clientId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"startTime":{"type":"string","format":"date-time","nullable":true,"description":"First function's start."},"endTime":{"type":"string","format":"date-time","nullable":true,"description":"First function's end."},"eventSpaceId":{"type":"string","nullable":true,"description":"First function's primary room."},"eventSpaceIds":{"type":"array","items":{"type":"string"},"description":"Every room the first function is booked into (primary room first)."},"guestCount":{"type":"integer","nullable":true,"description":"First function's guest count, falling back to the event's estimate."}}}}}}