REST API Quickstart
Mint a personal access token, call your first endpoint and receive your first signed webhook, end to end in under five minutes.
By the end of this page you will have a working zg_ API token, a successful GET /v1/teams/current call, and a webhook endpoint receiving project.created events.
Prerequisites
- A Zuse Bifrost account in a team, with a role that carries the abilities below
- A terminal with
curl, or an HTTP client of your choice
Mint an API token
Open Account Settings → API Tokens and press Create Token. Tick these abilities:
team:view, so the token can identify the team it is scoped toproject:view-anyandproject:view, read-only project accesswebhook-endpoint:create, so the same token can register a webhook endpoint
Leave the team on the one you are working in; the token receives its scope:team:<uuid> entry from that choice. Press Create. The plaintext token (zg_live_...) is shown once; copy it now, it is not retrievable later. API tokens covers the page in full.
Confirm the token works
curl
curl "https://api.example.test/v1/teams/current" \
-H "Authorization: Bearer zg_live_..."PHP (Laravel Http)
use Illuminate\Support\Facades\Http;
$response = Http::withToken('zg_live_...')
->get(config('services.zusegenius.api').'/v1/teams/current');
$team = $response->json('data');Node (fetch)
const response = await fetch(`https://api.example.test/v1/teams/current`, {
headers: { Authorization: "Bearer zg_live_..." },
});
const { data: team } = await response.json();Python (requests)
import requests
response = requests.get(
"https://api.example.test/v1/teams/current",
headers={"Authorization": "Bearer zg_live_..."},
)
team = response.json()["data"]Expected response:
{
"data": {
"id": "a83f0d51-4c92-4b7e-8615-2fd9e70a3c86",
"name": "Zuse Technologies",
"owner_user_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
"created_at": "2026-10-26T07:12:33+00:00"
}
}Replace api.example.test with your workspace's API host, which your administrator gives you with the workspace address.
Register a webhook endpoint
Point a webhook.site URL (or any HTTPS endpoint you control) at project.created:
curl "https://api.example.test/v1/webhook-endpoints" \
-X POST \
-H "Authorization: Bearer zg_live_..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "First webhook",
"url": "https://webhook.site/<your-uuid>",
"events": ["project.created"]
}'Expected response (201 Created):
{
"data": {
"id": "c62a08f4-1b7d-4e35-9860-a37f5d21e0b9",
"name": "First webhook",
"events": ["project.created"],
"is_active": true
},
"secret": "whsec_abc123..."
}Copy the secret now. Later GET /v1/webhook-endpoints calls never
include it. Use it to verify every incoming ZG-Signature: t=...,v1=...
header; see signature verification.
Trigger an event
Create a project in Zuse Bifrost. Within a few seconds the webhook.site URL receives a POST with a project.created envelope.
Next steps
- Authentication: ability combinations, revocation, rotation
- Idempotency: make your retries safe
- Webhooks quickstart: signature verification, retry semantics
- Errors: every error code and its remediation
How is this guide?
Last updated on