101 — Your first API integration

What you'll build

In about ten minutes you'll end with a temporary HTTPS endpoint (RequestBin or equivalent) holding a real job.transition webhook delivery from your tenant. The body is what every later integration will receive.

Final proof — a single POST you can replay:

POST https://your-bin.requestbin.example HTTP/1.1
Content-Type: application/json
X-FastYoke-Event: job.transition
X-FastYoke-Delivery: wh_evt_01HXZ…
X-FastYoke-Timestamp: 1750905600
X-FastYoke-Signature: sha256=…

{
  "id": "wh_evt_01HXZ…",
  "event": "job.transition",
  "occurred_at": "2026-06-21T12:00:00Z",
  "tenant_id": "tnt_01HW…",
  "data": {
    "job_id": "job_…",
    "from_state": "Draft",
    "to_state": "Active",
    "event_name": "activate"
  }
}

Before you begin

• A FastYoke tenant you're an admin of. The free tier is fine.
• curl on your shell.
• A way to receive an HTTPS request. This tutorial uses RequestBin; ngrok and webhook.site work identically.

Steps

1. Mint a one-hour test token

Open the admin shell at Settings → Tokens → Generate test token. See the quick test token reference for the full explanation of what gets minted.

Copy the token. You now have a bearer that mirrors your admin session for one hour.

Checkpoint — list the tenant's PATs (the list may be empty; the 200 status is the win):

curl -i \
  -H "Authorization: Bearer $FY_TOKEN" \
  https://www.fastyoke.io/api/v1/tenant/api-tokens

Expected: HTTP/2 200 and a JSON array (possibly empty). Anything other than 200 means re-mint.

2. Find a schema with a transition

Your tenant has at least one FSM schema installed by default. GET /api/v1/tenant/schemas returns them.

curl -s -H "Authorization: Bearer $FY_TOKEN" \
  https://www.fastyoke.io/api/v1/tenant/schemas \
  | jq '.[0] | {name, entity, transitions: [.transitions[] | {event, from, to}]}'

Checkpoint — at least one transition is listed. If the array is empty, install a Yoke from the Marketplace (Yoke Ledger is free) and re-run.

Save the entity name and one event for the next steps.

3. Create an entity record

curl -s -X POST \
  -H "Authorization: Bearer $FY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payload":{"display_name":"My first record"}}' \
  https://www.fastyoke.io/api/v1/tenant/entities/<entity>

Checkpoint — response carries an id. Save it into $FY_ID. GET .../<id> returns the same body — that round-trip lets you verify the write landed.

4. Wire a webhook subscription

curl -s -X POST \
  -H "Authorization: Bearer $FY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-bin.requestbin.example",
    "events": ["job.transition"],
    "description": "101 tutorial"
  }' \
  https://www.fastyoke.io/api/v1/tenant/webhooks

Save the response id into $FY_SUB.

Checkpoint — fire a synthetic delivery and confirm it lands on your bin:

curl -s -X POST \
  -H "Authorization: Bearer $FY_TOKEN" \
  https://www.fastyoke.io/api/v1/tenant/webhooks/$FY_SUB/test

Within a few seconds, your RequestBin shows a POST with X-FastYoke-Event set.

5. Trigger a transition

curl -s -X POST \
  -H "Authorization: Bearer $FY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event":"<your-event-name>"}' \
  https://www.fastyoke.io/api/v1/tenant/jobs/$FY_ID/transition

Checkpoint — within seconds, the bin shows a POST with X-FastYoke-Event: job.transition and a body whose data.event_name matches your event.

What you built

• One new entity row in your tenant.
• One job.transition row in event_log.
• One webhook subscription rendered in Settings → Webhooks.
• One receipt at your RequestBin, ready to replay.

Next

201 — Sync data into FastYoke — production patterns wrapped around a CSV importer.