02 · Python, Go, Ruby and curl

Python, Go, Ruby and curl.

The Node SDK is a convenience. The API is HTTP and JSON, documented by an OpenAPI spec you can generate a client from.

Every request carries Authorization: Bearer with your workspace API key and uses snake_case JSON. The full spec is at https://api.notify.productcraft.co/docs-json; the API reference renders it.

Send a notification

POST /v1/workspaces/{workspace_id}/notifications requires an Idempotency-Key header. Derive it from your own event (comment-created:c_981) so a retry returns the same notification; the same key with a different body is a 409 IDEMPOTENCY_KEY_REUSE. Keys use only A-Z a-z 0-9 _ - : (no dots).

bash

curl -X POST "https://api.notify.productcraft.co/v1/workspaces/$PRODUCTCRAFT_WORKSPACE_ID/notifications" \
  -H "Authorization: Bearer $PRODUCTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: comment-created:c_981" \
  -d '{
    "type": "comment.created",
    "recipients": ["user_123"],
    "data": { "author": "Grace", "post_title": "Hello", "excerpt": "Lovely post!", "post_id": "p_42" }
  }'
# 202 {"id":"0193…","type":"comment.created","recipient_count":1,"status":"accepted","skipped":[]}

Create or update a recipient

PUT /recipients/{external_id} is an upsert keyed by your user id (URL-encode it). Fields you leave out are kept.

bash

curl -X PUT "https://api.notify.productcraft.co/v1/workspaces/$PRODUCTCRAFT_WORKSPACE_ID/recipients/user_123" \
  -H "Authorization: Bearer $PRODUCTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ada@example.com", "locale": "en", "timezone": "Europe/Lisbon" }'

Mint a recipient token for your frontend

Your frontend or app calls /v1/client/… with this token, never with your API key. Mints are not idempotent (each call returns a fresh token) and are limited to 3,000 a minute per workspace, so cache one per user for most of its lifetime.

bash

curl -X POST "https://api.notify.productcraft.co/v1/workspaces/$PRODUCTCRAFT_WORKSPACE_ID/recipient-tokens" \
  -H "Authorization: Bearer $PRODUCTCRAFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recipient": "user_123", "ttl_seconds": 3600 }'
# {"token":"eyJ…","expires_at":"…","scopes":[…],"recipient_id":"…","external_id":"user_123"}

Errors, retries and webhooks

Errors are one JSON shape for every ProductCraft API: {status_code, code, message, request_id, errors, details?}. Branch on code; see error codes.
Retry network errors, 429 (after Retry-After seconds) and 5xx with the same Idempotency-Key. Do not retry other 4xx.
Webhooks use Standard Webhooks signatures, so the standardwebhooks library for Python, Go or Ruby verifies them. See Webhooks.
Generating a client: any OpenAPI 3 generator works on /docs-json; the operation ids are stable.