Developer reference: REST API endpoints

REST + MCP reference for developers integrating with Convene Markets. Every REST endpoint has a matching MCP tool — see the MCP Tools section at the bottom.

Quick start

Get your API key from Settings → API Keys, then verify it works:

export TOKEN="fm_org_your_token_here"

curl -s -H "Authorization: Bearer $TOKEN" \
  https://app.convene.markets/api/v1/admin/dashboard

You should get back a JSON object like this:

{
  "organization": {
    "id": 1,
    "name": "FRESH Markets",
    "slug": "freshmarkets"
  },
  "pending_applications": 3,
  "pending_orders": 7,
  "upcoming_market_dates": 2,
  "next_market_date": "2026-04-19",
  "total_vendors": 142
}

If you get 401 Unauthorized, check that your token starts with fm_org_ and hasn't been revoked.

Authentication

Pass your token as a Bearer header on every request:

Authorization: Bearer fm_org_...

Tokens are organization-scoped. Every response is automatically filtered to your organization — attempting to access another org's resource returns 404 Not Found, not 403.

Base URL

https://app.convene.markets/api/v1/admin

All endpoints below are relative to this base URL.

Errors

Status	Meaning
401	Missing, invalid, or revoked token
403	Token creator was deactivated, lost admin role, lost org membership, or org is in draft status
404	Resource doesn't exist or belongs to another org
422	Validation error — body contains { "errors": [...] } or { "error": "..." }

Resources

Dashboard

• GET /dashboard — org summary: pending counts, financials, next upcoming market date

Vendor Applications

• GET /vendor_applications — list applications
• GET /vendor_applications/:id — single application
• PATCH /vendor_applications/:id — update status or add starter credits
• POST /vendor_applications/:id/remind — send payment-link reminder email
• POST /vendor_applications/:id/credit — attach a credit to the application

Query parameters for GET /vendor_applications:

Param	Type	Description
status	string	Filter by status: pending, approved, rejected, waitlisted
query	string	Search by vendor name or email
start_date	date	Applications submitted on or after this date (YYYY-MM-DD)
end_date	date	Applications submitted on or before this date (YYYY-MM-DD)
limit	integer	Max results to return (default 50)
offset	integer	Pagination offset (default 0)

# Approve an application
curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved", "send_notification": true}' \
  https://app.convene.markets/api/v1/admin/vendor_applications/456

Orders

• GET /orders — list orders (excludes archived by default)
• GET /orders/:id — single order with line items
• PATCH /orders/:id/approve — approve; optional body: { "trust_future_orders": true }
• PATCH /orders/:id/reject
• PATCH /orders/:id/archive
• PATCH /orders/:id/restore
• PATCH /orders/:id/modify — move a payment_pending order back to pending for re-payment
• PATCH /orders/:id/complete_zero_amount — mark a $0 order complete without payment
• POST /orders/:id/remind — send payment reminder email

# Approve order 789
curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://app.convene.markets/api/v1/admin/orders/789/approve

Bookings

• GET /bookings — list bookings
• GET /bookings/:id — single booking
• DELETE /bookings/:id/cancel — cancel a booking
• POST /bookings/:id/rebook — rebook with optional fee; remainder credited back to vendor
• PATCH /bookings/:id/restore — restore a cancelled booking
• PATCH /bookings/:id/space_number — assign a space number
• DELETE /bookings/bulk_cancel — cancel multiple bookings; body: { "booking_ids": [1, 2, 3] }

Query parameters for GET /bookings:

Param	Type	Description
date_filter	string	upcoming or past
market_id	integer	Filter to a specific market
query	string	Search by vendor name

# Assign space 14A to booking 321
curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"space_number": "14A"}' \
  https://app.convene.markets/api/v1/admin/bookings/321/space_number

Markets

• GET /markets — list markets; filter: status (published|unpublished), query
• GET /markets/:id
• PATCH /markets/:id — update market fields
• POST /markets/:id/send_email — email all active vendors for this market; body: message, optional subject, market_date_id

Market Dates

• GET /market_dates — list market dates; filter: market_id, date_filter
• GET /market_dates/:id
• POST /market_dates — create one date; body: { "market_id": 1, "market_date": { "scheduled_at": "2026-05-03" } }
• POST /market_dates/bulk_create — create recurring dates; body: market_id, start_date, end_date, day_of_week (0=Sun)
• PATCH /market_dates/:id
• POST /market_dates/:id/close_out — close a date and finalize attendance
• GET /market_dates/:id/bookings — list all bookings for a specific date

# Create every Saturday in May 2026
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"market_id": 1, "start_date": "2026-05-01", "end_date": "2026-05-31", "day_of_week": 6}' \
  https://app.convene.markets/api/v1/admin/market_dates/bulk_create

Vendors

• GET /vendors — list vendors; filter: query, start_date, end_date
• GET /vendors/:id — vendor detail including recent applications, orders, bookings, and credits (all org-scoped)
• POST /vendors/:id/send_email — send a direct message to the vendor
• GET /vendors/:vendor_id/notes — list internal notes on this vendor
• POST /vendors/:vendor_id/notes — add a note; body: { "note": "..." }

Credits

• GET /credits — list credits; filter: status (unexpired|expired), vendor_id, query
• GET /credits/:id
• POST /credits — issue a new credit; body: vendor_id, credit_amount, optional notes, expires_at
• PATCH /credits/:id — adjust balance or expiry; body: remaining_dollars, notes, expires_at
• DELETE /credits/:id — delete a credit

# Issue a $10 credit to vendor 55
curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": 55, "credit_amount": 10.00, "notes": "Makeup for cancelled date"}' \
  https://app.convene.markets/api/v1/admin/credits

MCP tools

Every endpoint above is also available as an MCP tool at POST /admin/mcp (JSON-RPC 2.0, protocol 2024-11-05). Call tools/list to get the full schema for each tool.

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://app.convene.markets/admin/mcp | jq '.result.tools[].name'

Current tool catalog (~30 tools):

Resource	Tools
Dashboard	get_dashboard, get_dashboard_summary
Applications	list_applications, get_application, update_application_status, send_application_reminder, add_application_credit
Orders	list_orders, get_order, approve_order, reject_order, archive_order, restore_order, modify_order, send_order_reminder
Bookings	list_bookings, get_booking, cancel_booking, rebook_booking, restore_booking, update_space_number, bulk_cancel_bookings
Markets	list_markets, get_market, update_market, send_market_email
Market Dates	list_market_dates, get_market_date, create_market_date, close_out_market_date, list_market_date_bookings
Vendors	list_vendors, get_vendor, send_vendor_email, list_vendor_notes, add_vendor_note
Credits	list_credits, create_credit, update_credit