Greenroom API v1

Build with the booking agent.

Ask DJ-specific booking questions through one persistent Agent API, or work directly with profiles, availability, show advancing, promoter events, invoices, booking calls, introductions, discovery, and match intelligence.

Base URL/api/v1

Agent accessDJ API key

Account limit300 / min

Download OpenAPI 3.1 Manage credentials

Quickstart

Get real data in one request.

The scene search endpoint is public and allows cross-origin browser reads, so your first request needs no account and no secret. It returns privacy-safe DJ and venue records in the same response shape used across v1.

curl

curl "https://greenroom.dance/api/v1/search?q=techno&city=Berlin&types=dj,venue&limit=4"

TypeScript

const response = await fetch(
  "https://greenroom.dance/api/v1/search?q=techno&city=Berlin"
);

if (!response.ok) throw new Error(`Greenroom returned ${response.status}`);
const { data, meta } = await response.json();
console.log(meta.count, data);

Python

import httpx

response = httpx.get(
    "https://greenroom.dance/api/v1/search",
    params={"q": "techno", "city": "Berlin", "limit": 4},
)
response.raise_for_status()
print(response.json()["data"])

Generate your own types

npx openapi-typescript https://greenroom.dance/api/v1/openapi.json \
  -o greenroom-api.d.ts

Agent API

DJ booking judgment in one call.

POST /agentcalls the same persistent booking agent used inside Greenroom. It can reason over the authenticated DJ's profile, remembered preferences, calendar, promoter matches, events, and introduction movement.

This is a specialist agent, not a general chat endpoint. Its behavior combines tested booking rules, persistent account context, reviewed feedback examples, and an optional language layer for wording. Internal prompts, traces, and training records are never exposed.

ReadsProfile + booking context

Can changeProfile, memory, calendar

ResponseReply + effects + receipt

Current roleDJ accounts

curl https://greenroom.dance/api/v1/agent \
  -X POST \
  -H "Authorization: Bearer $GREENROOM_API_KEY" \
  -H "Idempotency-Key: agent-turn-01J8X4V6M2" \
  -H "Content-Type: application/json" \
  -d '{"message":"Which Berlin promoters fit my sound, and why?"}'

{
  "data": {
    "reply": "Start with...",
    "intent": "matches",
    "payload": { "kind": "matches", "matches": [] },
    "effects": {
      "changes": ["Remembered: Asked about promoter matches in Berlin"],
      "profileChanged": false,
      "memoryAdded": ["Asked about promoter matches in Berlin"],
      "calendarEntry": null,
      "removedCalendarEntryIds": []
    },
    "receipt": {
      "id": "agact_...",
      "description": "Remembered: Asked about promoter matches in Berlin",
      "status": "applied"
    }
  }
}

Show every effect

Render the reply for the user, then inspect effects before updating your own UI. The response separates profile, memory, and calendar changes from conversational text.

data.reply
data.effects
data.receipt

Keep turns retry-safe

Send one Idempotency-Key per logical turn. A timeout can then be retried without repeating the agent action or duplicating its transcript.

Idempotency-Key: agent-turn-UNIQUE_ID

Undo supported actions

A mutation returns a receipt. Send a new message such as “undo that” to reverse the latest supported profile, memory, or calendar action.

{"message":"undo that"}

Live explorer

Change the signal. Read the JSON.

This is a real request to GET /search. Use it to understand filters and response structure before wiring the endpoint into your product.

Live signal

idle

GET/api/v1/search

citygenre

Request path

/api/v1/search?types=dj%2Cvenue&limit=4&q=techno&city=Berlin

JSON responseWaiting

Run the request to see a live response.

Authentication

One credential, one account.

API keys inherit the owning account role. Create one in the developer console, store it as a server-side secret, and send it in the Authorization header. OAuth access tokens are limited to the approved DJ calendar surface. Revocation takes effect on the next request.

curl "https://greenroom.dance/api/v1/calendar?kind=gig&limit=20" \
  -H "Authorization: Bearer $GREENROOM_API_KEY"

Pagination

Follow the cursor.

Collections default to 25 records and accept up to 100. Pass the returned nextCursor back as cursor. Treat cursors as opaque values.

{"meta":{"count":20,"hasMore":true,"nextCursor":"eyJvZmZzZXQiOjIwfQ"}}

Errors

Stable codes, readable context.

Failures return an error object with a machine code and message. Use HTTP status for the broad class and the code for integration logic. A 429 response includes Retry-After.

{"error":{"code":"invalid_request","message":"endsOn must be on or after startsOn."}}

Incremental sync

Move only what changed.

Calendar and invoice lists accept updated_after. Introductions accept created_after. Dates use YYYY-MM-DD and timestamps use ISO 8601.

Production reliability

Retry safely. Keep the receipt.

Network failures happen between your server and Greenroom. These controls let your integration recover without guessing what happened.

Idempotent creates

Send a unique Idempotency-Key with agent turns and calendar, event, invoice, or opportunity creates. Greenroom stores the response for 24 hours. An exact replay returns Idempotency-Replayed: true. Reusing a key with different JSON returns 422.

Idempotency-Key: booking_01J8X4V6M2
Idempotency-Replayed: true

Request tracing

Every v1 response includes a request ID and API version. Keep the request ID with your logs and include it when reporting a failed request.

X-Greenroom-Request-Id: 4d02...
X-Greenroom-API-Version: 1

Rate handling

Authenticated accounts receive 300 requests per minute. Read RateLimit-Policy, honor Retry-After on 429, and retry with exponential backoff plus jitter.

RateLimit-Policy: "account";q=300;w=60
Retry-After: 24

Write recovery

Retry timeouts and 5xx responses with the same idempotency key. Do not retry validation or permission failures until the request changes.

retry: timeout, 500, 502, 503, 504
stop: 400, 401, 403, 404, 422

Build recipes

Choose a useful first loop.

Each recipe combines a small set of endpoints into a product behavior you can ship and test independently.

POST /agentRender effectsGET /agent

Embedded DJ booking agent

Put Greenroom's booking judgment in an artist app, dashboard, or team tool while keeping the conversation and memory attached to the DJ.

GET /searchGET /locationsGET /public-directory

Scene discovery

Power city guides, venue maps, and artist discovery without exposing private contact data.

POST /matchesPOST /opportunitiesGET /intros

Promoter booking assistant

Rank artists for an event brief, publish the booking call, then track introductions.

GET /availabilityPOST /calendarcalendar.created

Tour availability sync

Find route gaps, create a hold with an idempotency key, and react to the signed change.

Install MCP23 typed toolsask_greenroom_agent

Conversational booking desk

Give an MCP client the trained booking agent plus permissioned profile, calendar, finance, discovery, and matching tools.

Connected apps

Consent and change delivery.

DJ accounts can register OAuth clients and signed webhook endpoints in the developer console. Client secrets and webhook secrets are shown once.

OAuth Authorization Code

Generate a new PKCE verifier for every authorization attempt and keep it in the user's server-side session. Send the S256 challenge, exact registered HTTPS redirect URI, and an opaque state value. Exchange the one-time code within ten minutes with the original verifier. The returned Bearer token carries the calendar scope and works on /me and calendar operations.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(32).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");

https://greenroom.dance/oauth/authorize
  ?response_type=code
  &client_id=CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example%2Fgreenroom%2Fcallback
  &state=OPAQUE_STATE
  &code_challenge=BASE64URL_SHA256
  &code_challenge_method=S256

curl https://greenroom.dance/api/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=ONE_TIME_CODE \
  -d redirect_uri=https://app.example/greenroom/callback \
  -d code_verifier=ORIGINAL_PKCE_VERIFIER

Signed webhooks

Subscribe a reachable public HTTPS endpoint to calendar.created, calendar.updated, and calendar.deleted. Greenroom signs the exact JSON body with HMAC-SHA256.

Greenroom-Signature: sha256=HEX_HMAC
User-Agent: Greenroom-Webhooks/1.0

Compute HMAC-SHA256 with the webhook secret, compare the hexadecimal digest in constant time, and reject mismatches before processing the event. The payload includes id, event, createdAt, and data.

MCP server

Install the booking specialist.

Tell Claude Code, “Install the Greenroom MCP.” Give it the installer record at /api/mcp/install, or run the command directly after setting GREENROOM_API_KEY. A DJ account can then call ask_greenroom_agent for domain-specific booking help, with the same persistent thread and effects receipts as REST.

claude mcp add --transport http --scope user \
  greenroom https://greenroom.dance/api/mcp \
  --header 'Authorization: Bearer ${GREENROOM_API_KEY}'

Transport: stateless Streamable HTTP. Endpoint: https://greenroom.dance/api/mcp. Contract resource: greenroom://api/openapi.

Booking agent

ask_greenroom_agent
Ask a persistent DJ booking question and receive explicit effects.

Profile

get_account
Identify the account attached to the key.
get_profile
Read the owned DJ or promoter profile.
update_dj_profile
Merge public, booking, and travel fields.
update_promoter_profile
Merge claimed promoter profile fields.

Show operations

list_calendar
Search DJ calendar entries.
check_availability
Classify available, booked, blocked, and travel days.
create_calendar_entry
Create a city, blocked date, or gig.
update_show_desk
Replace deal, advancing, travel, and tasks.
inspect_show_readiness
Audit advancing gaps and unfinished tasks.

Promoter and finance

list_promoter_events
Search events owned by the promoter.
create_promoter_event
Create a draft or published event.
list_invoices
Search account-owned invoices.
create_invoice_draft
Create an unsent invoice draft.

Network intelligence

list_booking_opportunities
Find visible booking calls.
publish_booking_opportunity
Publish a follower or network call.
list_introductions
Check introduction movement.
respond_to_introduction
View, reply, accept, or decline.
search_venues
Search the sourced public venue directory.
search_djs
Search public DJ profiles.
search_network
Search privacy-safe counterpart profiles.
recommend_promoters
Rank promoter fit with explanations.
recommend_djs_for_event
Rank visible DJs against an event brief.

REST reference

Every operation in v1.

This reference is rendered from the same OpenAPI 3.1 contract returned by the API. Request ownership, role checks, and contact privacy are enforced server-side. Open any operation to see parameters, request body type, access level, and response statuses.

Identity

Bearer credential identity and API-key-owned profile.

get/api/v1/meGet the Bearer credential ownerBearer / OAuth

Operation IDgetCurrentAccount

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

get/api/v1/profileGet the DJ or promoter profile owned by the API keyAny key

Operation IDgetAccountProfile

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

patch/api/v1/profileMerge editable fields into the account profileAny key

Operation IDupdateAccountProfile

Request bodyRole-specific profile patch

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Agent

Greenroom's persistent, DJ-specific booking intelligence over authorized account context.

get/api/v1/agentRead the DJ booking agent thread and memoryDJ key

Operation IDgetAgentThread

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

post/api/v1/agentAsk Greenroom's persistent DJ booking agentDJ key

Operation IDaskBookingAgent

Request bodyAgentTurnInput

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

Idempotency-KeyheaderOptional unique key for safely retrying this create request for 24 hours. Reusing a key with a different body returns 422.

Operations

Calendar, show desk, and promoter event workflows.

get/api/v1/calendarList travel, gig, and blocked calendar entriesDJ key / OAuth

Operation IDlistCalendarEntries

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

kindqueryComma-separated city, gig, or blocked values.

fromqueryInclude entries ending on or after this YYYY-MM-DD date.

toqueryInclude entries starting on or before this YYYY-MM-DD date.

updated_afterqueryInclude entries changed after this ISO 8601 timestamp.

qquerySearch title, city, venue, and notes.

post/api/v1/calendarCreate a calendar entry or confirmed show deskDJ key / OAuth

Operation IDcreateCalendarEntry

Request bodyCalendarEntryInput

Responses201, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

Idempotency-KeyheaderOptional unique key for safely retrying this create request for 24 hours. Reusing a key with a different body returns 422.

patch/api/v1/calendarReplace a show desk using the legacy collection routeDJ key / OAuth

Operation IDreplaceLegacyShowDesk

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Deprecated compatibility route. New integrations should use the resource detail path.

delete/api/v1/calendarDelete a calendar entry using the legacy collection routeDJ key / OAuth

Operation IDdeleteLegacyCalendarEntry

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Deprecated compatibility route. New integrations should use the resource detail path.

Parameters

idqueryCalendar entry ID.

get/api/v1/calendar/{id}Get one calendar entry and its show deskDJ key / OAuth

Operation IDgetCalendarEntry

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

patch/api/v1/calendar/{id}Update calendar, deal, contract, advancing, travel, tasks, or settlementDJ key / OAuth

Operation IDupdateCalendarEntry

Request bodyCalendarEntryPatch

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

delete/api/v1/calendar/{id}Delete a calendar entryDJ key / OAuth

Operation IDdeleteCalendarEntry

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

get/api/v1/availabilityBuild a daily availability plan from the DJ calendarDJ key / OAuth

Operation IDgetAvailabilityPlan

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

fromquery · requiredFirst date in the availability window, formatted as YYYY-MM-DD.

toquery · requiredLast date in the availability window, formatted as YYYY-MM-DD.

get/api/v1/eventsList events owned by a promoter accountPromoter key

Operation IDlistPromoterEvents

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

statusqueryComma-separated draft or published values.

fromqueryInclude events on or after this YYYY-MM-DD date.

toqueryInclude events on or before this YYYY-MM-DD date.

qquerySearch title, city, and venue.

post/api/v1/eventsCreate a promoter eventPromoter key

Operation IDcreatePromoterEvent

Request bodyEventInput

Responses201, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

Idempotency-KeyheaderOptional unique key for safely retrying this create request for 24 hours. Reusing a key with a different body returns 422.

get/api/v1/events/{id}Get one promoter eventPromoter key

Operation IDgetPromoterEvent

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

patch/api/v1/events/{id}Update a promoter eventPromoter key

Operation IDupdatePromoterEvent

Request bodyEventPatch

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

delete/api/v1/events/{id}Delete a promoter eventPromoter key

Operation IDdeletePromoterEvent

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

Finance

Account-owned invoice workflows.

get/api/v1/invoicesList account invoicesAny key

Operation IDlistInvoices

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

statusqueryComma-separated draft, sent, paid, overdue, or void values.

due_fromqueryInclude invoices due on or after this YYYY-MM-DD date.

due_toqueryInclude invoices due on or before this YYYY-MM-DD date.

updated_afterqueryInclude invoices changed after this ISO 8601 timestamp.

qquerySearch number, recipient, event, venue, and city.

post/api/v1/invoicesCreate and optionally send an invoiceAny key

Operation IDcreateInvoice

Request bodyInvoiceInput

Responses201, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

Idempotency-KeyheaderOptional unique key for safely retrying this create request for 24 hours. Reusing a key with a different body returns 422.

get/api/v1/invoices/{id}Get one invoiceAny key

Operation IDgetInvoice

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

patch/api/v1/invoices/{id}Send or void an invoiceAny key

Operation IDactOnInvoice

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

Network

Booking opportunities, introductions, and visible counterparts.

get/api/v1/opportunitiesList visible booking opportunitiesAny key

Operation IDlistBookingOpportunities

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

statusqueryComma-separated open or closed values.

cityqueryMatch an exact city.

fromqueryInclude opportunities on or after this YYYY-MM-DD date.

toqueryInclude opportunities on or before this YYYY-MM-DD date.

qquerySearch title, description, city, and venue.

post/api/v1/opportunitiesPublish a booking opportunityPromoter key

Operation IDcreateBookingOpportunity

Request bodyOpportunityInput

Responses201, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

Idempotency-KeyheaderOptional unique key for safely retrying this create request for 24 hours. Reusing a key with a different body returns 422.

get/api/v1/opportunities/{id}Get a visible booking opportunityAny key

Operation IDgetBookingOpportunity

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

patch/api/v1/opportunities/{id}Open or close an owned booking opportunityPromoter key

Operation IDupdateBookingOpportunity

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

get/api/v1/introsList account introduction movementAny key

Operation IDlistIntroductions

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

statusqueryComma-separated sent, viewed, replied, accepted, or declined values.

created_afterqueryInclude introductions created after this ISO 8601 timestamp.

get/api/v1/intros/{id}Get one introductionAny key

Operation IDgetIntroduction

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

patch/api/v1/intros/{id}Record a promoter response to an introductionPromoter key

Operation IDupdateIntroduction

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

idpath · requiredOpaque Greenroom resource ID.

get/api/v1/locationsList supported booking marketsAny key

Operation IDlistLocations

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

country_codequeryMatch a two-letter country code.

regionqueryMatch a Greenroom region.

qquerySearch location name, slug, and aliases.

get/api/v1/networkFind visible accounts on the other side of the boothAny key

Operation IDlistNetworkCounterparts

Request bodyNone

Responses200, 400, 401, 403, 404, 409, 422, 429, 500

Parameters

limitqueryinteger. Default: 25

cursorqueryOpaque cursor returned by the previous page.

cityqueryMatch an exact city.

genrequeryMatch an exact genre.

qquerySearch public profile fields.