$ semuko --help

Build on Semuko.

One versioned catalog powers both a REST API at /api/v1 and an MCP server at /api/v1/mcp. Use it from scripts, Make, n8n, or your AI app of choice.

API & MCP on Studio Pro and Agency Unlimited

Get an API key →openapi.json

129operations

46scopes

5webhook events

120/minrate limit per key

curl -s "$SEMUKO_HOST/api/v1/leads?limit=2" \ -H "Authorization: Bearer sk_live_••••" \ -H "Accept: application/json"

HTTP/1.1 200 OK84msratelimit-remaining: 119

{ "data": [ { "id": "ld_8f2c…", "name": "Ana & Marco", "status": "Inquiry", "eventDate": "2027-06-12", "brand": "Ellis Studio" }, { "id": "ld_41aa…", "name": "Chen Family", "status": "Consult booked", "eventDate": "2026-11-02", "brand": "Ellis Studio" } ], "page": 1, "limit": 2 }

01 · Quickstart

From zero to 200 OK in three steps.

01Create a key

Open Settings → Preferences → Developer in Semuko Admin. Copy the secret; it is shown once and stored as a SHA-256 hash.

$export SEMUKO_KEY=sk_live_••••

02Make a call

Send it as a Bearer token. Staff login sessions are never accepted on /api/v1.

$curl -H "Authorization: Bearer $SEMUKO_KEY" $SEMUKO_HOST/api/v1/leads

03Or hand it to your AI

Point Claude, ChatGPT, Gemini CLI or Cursor at the MCP URL. Same key, filtered tools.

$$SEMUKO_HOST/api/v1/mcp

02 · API explorer

129 operations. Poke at any of them.

Each operation is both a REST route and an MCP tool, with the same scopes. Layers go from reading CRM data (L1), to money and paperwork (L2), to actions that reach clients (L3).

GET/api/v1/leads

List leads with pagination and optional search

MCP toolsemuko_list_leads

Scopescrm.read

Risk classread

request

curl -X GET "$SEMUKO_HOST/api/v1/leads" \ -H "Authorization: Bearer sk_live_••••"

200 OK { "data": [ { "id": "…" }, { "id": "…" } ], "page": 1, "limit": 25 }

Example data. Your responses come from your own studio.

03 · Scopes

Least privilege, by default.

New keys start with crm.read only. Toggle scopes to see what a key can reach. Write scopes include their read scope automatically.

key preview38/129 operations unlocked

{ "keyPrefix": "sk_live_3c9e", "secret": "sk_live_•••• (shown once)", "scopes": ["crm.read", "locations.read", "vendors.read", "equipment.read", "packages.read", "products.read", "asks.read", "gift_cards.read", "tags.read", "beacon.read", "schedule.read"] }

✓semuko_list_leadsL1

✓semuko_get_leadL1

·semuko_create_leadL1

·semuko_update_leadL1

✓semuko_list_clientsL1

✓semuko_get_clientL1

·semuko_create_clientL1

·semuko_update_clientL1

✓semuko_list_eventsL1

✓semuko_get_eventL1

·semuko_create_eventL1

·semuko_update_eventL1

✓semuko_list_projectsL1

✓semuko_get_projectL1

·semuko_create_projectL1

·semuko_update_projectL1

✓semuko_list_brandsL1

✓semuko_list_statusesL1

✓semuko_list_typesL1

✓semuko_list_custom_fieldsL1

·semuko_list_webhooksL1

·semuko_create_webhookL1

·semuko_delete_webhookL1

·semuko_list_invoicesL2

·semuko_get_invoiceL2

·semuko_create_invoiceL2

·semuko_list_paymentsL2

·semuko_list_contractsL2

·semuko_get_contractL2

·semuko_create_contract_from_templateL2

·semuko_list_questionnairesL2

·semuko_assign_questionnaireL2

·semuko_list_bookingsL2

·semuko_get_bookingL2

·semuko_create_bookingL2

·semuko_list_galleriesL2

·semuko_get_galleryL2

·semuko_create_galleryL2

·semuko_update_galleryL2

·semuko_list_gallery_setsL2

·semuko_create_gallery_setL2

·semuko_update_gallery_setL2

·semuko_list_gallery_mediaL2

·semuko_get_gallery_selectionsL2

·semuko_create_gallery_uploadL2

·semuko_complete_gallery_uploadL2

·semuko_abort_gallery_uploadL2

·semuko_update_gallery_mediaL2

·semuko_replace_gallery_mediaL2

·semuko_complete_gallery_media_replaceL2

·semuko_abort_gallery_media_replaceL2

·semuko_delete_gallery_mediaL2

·semuko_apply_workflowL3

·semuko_convert_leadL3

·semuko_send_emailL3

·semuko_send_invoiceL3

·semuko_send_contractL3

✓semuko_list_locationsL2

✓semuko_get_locationL2

·semuko_create_locationL2

·semuko_update_locationL2

✓semuko_list_vendorsL2

✓semuko_get_vendorL2

·semuko_create_vendorL2

·semuko_update_vendorL2

✓semuko_list_equipmentL2

✓semuko_get_equipmentL2

·semuko_create_equipmentL2

·semuko_update_equipmentL2

✓semuko_list_equipment_kitsL2

✓semuko_get_equipment_kitL2

·semuko_create_equipment_kitL2

·semuko_update_equipment_kitL2

✓semuko_list_packagesL2

✓semuko_get_packageL2

·semuko_create_packageL2

·semuko_update_packageL2

✓semuko_list_productsL2

✓semuko_get_productL2

·semuko_create_productL2

·semuko_update_productL2

✓semuko_list_asksL2

✓semuko_get_askL2

·semuko_start_askL2

✓semuko_list_ask_startersL2

✓semuko_get_ask_starterL2

·semuko_create_ask_starterL2

·semuko_update_ask_starterL2

✓semuko_list_gift_cardsL2

✓semuko_get_gift_cardL2

·semuko_create_gift_cardL2

·semuko_update_gift_cardL2

✓semuko_list_tagsL2

✓semuko_get_tagL2

·semuko_create_tagL2

·semuko_update_tagL2

✓semuko_list_beacon_pagesL2

✓semuko_get_beacon_pageL2

·semuko_create_beacon_pageL2

·semuko_update_beacon_pageL2

·semuko_publish_beacon_pageL2

✓semuko_list_beacon_packsL2

✓semuko_get_beacon_packL2

·semuko_create_beacon_packL2

·semuko_update_beacon_packL2

✓semuko_list_schedule_postsL2

✓semuko_get_schedule_postL2

·semuko_create_schedule_postL2

·semuko_update_schedule_postL2

·semuko_reschedule_schedule_postL2

·semuko_list_omni_offersL2

·semuko_get_omni_offerL2

·semuko_create_omni_offerL2

·semuko_update_omni_offerL2

·semuko_publish_omni_offerL2

·semuko_list_omni_offer_itemsL2

·semuko_add_omni_offer_itemL2

·semuko_update_omni_offer_itemL2

·semuko_reorder_omni_offer_itemsL2

·semuko_list_timelinesL2

·semuko_get_timelineL2

·semuko_create_timelineL2

·semuko_upsert_timeline_sectionL2

·semuko_upsert_timeline_itemL2

·semuko_reorder_timeline_sectionsL2

·semuko_list_workflow_templatesL2

·semuko_get_workflow_templateL2

·semuko_create_workflow_templateL2

·semuko_update_workflow_templateL2

04 · MCP

Plug your studio into any AI client.

The MCP server uses Streamable HTTP. Tools are filtered by the key's scopes, and hard deletes are never exposed.

Add Semuko as a custom connector with your MCP URL. Remote clients can sign in with OAuth, or you can pass a Bearer key from a local config.

// claude_desktop_config.json { "mcpServers": { "semuko": { "url": "$SEMUKO_HOST/api/v1/mcp", "headers": { "Authorization": "Bearer sk_live_••••" } } } }

OAuth 2.1 for remote MCP

PKCE · S256 · CIMD

AI client

Semuko

You (admin)

→discover /.well-known

←authorization server metadata

→authorize + PKCE S256

✓approve at /admin/oauth/consent

←auth code → POST /api/oauth/token

⚡oat_•••• → tools/list

Access tokens use the oat_ prefix and are hashed at rest. Discovery: /.well-known/oauth-authorization-server

05 · Webhooks

Don't poll. Get pinged.

Subscribe with POST /api/v1/webhooks. Each delivery is a JSON POST with an event, timestamp and data envelope.

SSRF-guarded URLsredirects never followed10s timeoutfilter by brand

POST https://your-app.dev/hooks/semukolistening

16:16:16200contract.signed188ms

16:15:55200checkout.completed151ms

16:14:38200questionnaire.response_received114ms

16:13:21200lead.updated77ms

16:12:04200lead.created40ms

{ "event": "lead.created", "timestamp": "2026-10-01T16:12:04.118Z", "data": { "id": "ld_8f2c…", "name": "Ana & Marco", "status": "Inquiry", "customFields": { "venue": "Hotel du Lac" } } }

06 · Errors & limits

Predictable when things go sideways.

120 requests / minute

per key · RateLimit-* headers

idle · 0 / 120

every error, one shape

HTTP/1.1 403 { "error": "Missing required scope: crm.write", "code": "forbidden", "requestId": "req_0…" }

07 · Security

Paranoid on purpose.

When you connect MCP to a third-party AI, any CRM data you request is sent to that model. Only grant the scopes you need.

[✓]Staff login JWTs and cookies are never accepted on /api/v1

[✓]API secrets are hashed at rest and shown once

[✓]Writes and sends require explicit scopes

[✓]Hard deletes are not exposed on MCP

[✓]OAuth tokens (oat_) are hashed at rest

[✓]Client-facing actions are classed confirm_write

Ship something weird and useful.

Prefer no-code? Zapier keeps working on /api/zapier. See all integrations.

Start free trial →GET openapi.json

$ semuko ping → GET /api/v1/openapi.json ✓ openapi 3.1 · 129 operations ✓ mcp · streamable http ✓ oauth 2.1 · pkce s256 $ _