API und MCP für Entwickler und KI-Agenten

Services at a glance

GDTF fixture library (JSON API)

The API returns the same data as the catalog on gdtf-lights.com, read-only: 10,500+ fixtures with DMX modes, specifications and download links (GDTF file, GDTF Share, DMX channel list and, where available, Avolites Titan .d4). Neither the website nor the API publishes prices or stock: pr and prWeb are null, stock is 0.

• /api/catalog/list – search and listing with filters (q, category, manufacturer, dmxChannels, sort = default, name, manufacturer, power, weight, dmx; dir, offset, limit)
• /api/catalog/product?slug=… or ?id=… – fixture detail with all DMX modes and download links
• /api/catalog/lookup?needles=… – lookup by names (tolerant to case and punctuation)
• /api/catalog/by-ids?ids=… – fixtures by ID
• /api/catalog/status and /api/catalog/bootstrap – catalog status, categories and settings
• Nothing is ordered through the API. A link that opens fixtures in My list: https://gdtf-lights.com/?cart=ID:COUNT,ID:COUNT&clear=2

Choose the language with lang=cs|de|es (English is the default). The rental equipment catalog with prices has the same API on stagelights.cz: API guide on stagelights.cz.

MCP server (Model Context Protocol)

A remote MCP server for AI assistants and agents runs at https://gdtf-lights.com/mcp (add ?lang=cs|de|es for another catalog language). It uses stateless Streamable HTTP with no login: send JSON-RPC 2.0 messages with POST; GET returns 405. Connect it in any MCP client that supports a remote HTTP server.

Tools:

• search_fixtures, get_fixture, get_gdtf_download, list_categories – fixture search, detail with all DMX modes and a link to the GDTF file
• match_dmx_channels – finds a fixture and its DMX mode from a channel list
• prepare_mvr_export – checks fixtures, counts and modes and returns a job for the generator and a link to the MVR export page
• generate_mvr and get_mvr_job – create the MVR file and return a download link (the only tool that creates anything)
• list_layouts, list_scene_templates, list_visualizers – layouts, scene templates and program profiles

MVR 3D scene generator

The public API creates the same file as generate_mvr: POST to https://gdtf-lights.com/mvr-generate.php with the job from prepare_mvr_export as the JSON body. GDTF files come from the catalog; your own can be added as the multipart field gdtf[]. The response carries download_url, report_url and expires: download within 2 hours (scenes over 50 MB within 30 minutes). Lists of programs and layouts are available with GET, e.g. ?action=visualizers. For people, the same generator is on the MVR export page.

DMX → GDTF (Fixture Finder)

Finding a fixture by its DMX channels has its own API (https://gdtf-lights.com/dmx-to-gdtf, POST with a channels field) and the MCP tool match_dmx_channels; a separate MCP server with only this tool runs at https://gdtf-lights.com/mcp/dmx-to-gdtf. Details and examples are next to the tool: gdtf-lights.com/dmx-to-gdtf#api.

Examples

curl -s 'https://gdtf-lights.com/api/catalog/list?q=moving+head&sort=name&dir=asc&limit=5'

curl -s https://gdtf-lights.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

curl -s 'https://gdtf-lights.com/mvr-generate.php?action=visualizers'

Limits and errors

• Catalog API and MCP: 10 requests per second per IP address (bursts up to 60).
• MVR generation (API and generate_mvr together): 2,000 per day and 10 per minute per IP address.
• DMX → GDTF (API and match_dmx_channels): 20,000 per day and 300 per minute per IP address; for all clients together 500 per minute, 10,000 per hour and at most 3 searches at a time.
• Errors are machine-readable with a code field (e.g. rate_day, rate_minute, busy). 429 and 503 also carry Retry-After; wait that long. Daily limits reset at midnight UTC.
• Usage is counted in aggregate, without IP addresses.

For AI agents on the website

• Rules for AI: llms.txt and llms-full.txt; machine description: openapi.json (OpenAPI 3.1, API catalog per RFC 9727 at /.well-known/api-catalog).
• Names of all fixtures for AI (CSV, one column nazev): produkty_kb_en.csv.

Rules

Neither the website nor the API publishes prices or availability; equipment rental from SOH with prices is on stagelights.cz. AI visualizations (images and videos) are generated only on the website with the visitor’s consent; the API does not offer them. For integration questions, use the contact page.

Privacy (API and MCP for DMX → GDTF)

Covers the JSON API https://gdtf-lights.com/dmx-to-gdtf and the MCP servers https://gdtf-lights.com/mcp/dmx-to-gdtf and https://gdtf-lights.com/mcp (tool match_dmx_channels). Operator: SOH Sound & Lights s.r.o., Antala Staška 242/14, Prague 4, Czech Republic.

• No account or sign-in. The API and MCP set no cookies and use no analytics scripts.
• What you send (DMX channel list, manufacturer, options) is used only to compute the answer. We do not store it, do not use it to train models and do not share it.
• We use your IP address for the per-IP limits. It is part of the name of a counter file that we delete within 2 days; for IPv6 only the /64 prefix.
• The web server log records the IP address, time, requested address (not the request body), status, response size, referrer and User-Agent. We delete it within 15 days.
• Usage statistics: daily totals per tool, result and client software family (from the User-Agent or the MCP client name), without IP addresses. The number of different clients is only estimated: a hash of the IP address with a key that changes every day sets one bit of a bitmap and cannot be turned back into an address. We keep statistics for 90 days.
• We process the data on our rented server; we do not sell it or pass it to third parties. Legal basis: legitimate interest in running and protecting the service (GDPR Art. 6(1)(f)).
• You have the right to access, erasure, restriction and objection, and to lodge a complaint with the Czech Office for Personal Data Protection (ÚOOÚ). Contact us via the contact page.