BILETELIVE API · V1

Developer documentation

Read-only event and organizer APIs, plus signed outbound webhooks.

Base URL

https://biletelive.ro/api/v1

Authentication

Public event endpoints do not require authentication. Organizer endpoints use a Bearer API key created from Organizer → Developers / API.

Authorization: Bearer bl_live_xxxxxxxx.SECRET

The full API key is shown only once. BileteLive stores only its SHA-256 hash.

Scopes

events:read — read the organizer’s events.
orders:read — read the organizer’s orders and safe ticket metadata.
customers:read — additionally expose buyer name/email/phone in an authorized order response.
webhooks:manage — register webhook endpoints, inspect deliveries and replay them.

Public event endpoints

GET /api/v1/events
GET /api/v1/events/{slug}
GET /api/v1/events/{slug}/availability

Availability includes ticket quantities and public table states. Reservation holder data is never exposed.

Read-only MCP server

AI clients and agent tools can connect to BileteLive through the public Model Context Protocol endpoint. The MCP server is read-only and exposes only public event discovery, ticket inventory, anonymous table availability, and canonical booking links.

https://biletelive.ro/mcp

Available tools:

search_events
get_event
get_ticket_availability
get_table_availability
get_artist_events
get_venue_events
get_event_booking_url

The MCP server never exposes customer details, order data, QR credentials, payment data, or reservation-holder identity.

Organizer endpoints

GET /api/v1/me
GET /api/v1/organizer/events
GET /api/v1/orders/{id}
GET /api/v1/orders/{id}/tickets

Ticket responses intentionally exclude QR tokens and private admission credentials.

Webhook management

GET  /api/v1/webhooks
POST /api/v1/webhooks
GET  /api/v1/webhooks/{id}/deliveries
POST /api/v1/webhook-deliveries/{id}/replay

Webhook secrets are shown only once. Production endpoints must use HTTPS and may not resolve to private/reserved network addresses.

Webhook events

order.paid
order.refunded
order.cancelled
ticket.reissued
ticket.checked_in
event.updated
event.cancelled
inventory.updated

Webhook envelope

{
  "id": "0a8b...uuid",
  "type": "order.paid",
  "created_at": "2026-09-26T12:34:56+03:00",
  "data": {
    "order_id": 123,
    "event_id": 5,
    "currency": "RON",
    "total_cents": 10300
  }
}

Signature verification

Each request contains:

BileteLive-Event-Id: <uuid>
BileteLive-Event: order.paid
BileteLive-Timestamp: <unix timestamp>
BileteLive-Signature: v1=<hex hmac>

The signed value is {timestamp}.{raw_request_body} using HMAC-SHA256 and your webhook secret.

$signed = $timestamp . '.' . $rawBody;
$expected = 'v1=' . hash_hmac('sha256', $signed, $webhookSecret);
$valid = hash_equals($expected, $signatureHeader);

Example request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://biletelive.ro/api/v1/organizer/events

Rate limits and retries

API requests are limited per IP or API key. Webhooks are attempted immediately and retried after failures with increasing delays. Delivery status and manual replay are available to the organizer.

Versioning

All current endpoints live under /api/v1. Breaking changes will be introduced under a new API version rather than silently changing V1 contracts.