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.
1
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 are 1 to 256 of A-Z a-z 0-9 . _ : -; any other character is a 400 that names it.
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":[]}# pip install requests
import os
import requests
BASE = "https://api.notify.productcraft.co/v1/workspaces/" + os.environ["PRODUCTCRAFT_WORKSPACE_ID"]
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["PRODUCTCRAFT_API_KEY"]
# Create or update the recipient (your user id is the key).
session.put(f"{BASE}/recipients/user_123", json={"email": "ada@example.com", "locale": "en"}, timeout=10).raise_for_status()
# Send. A deterministic Idempotency-Key makes a retry safe.
res = session.post(
f"{BASE}/notifications",
json={"type": "comment.created", "recipients": ["user_123"], "data": {"author": "Grace", "post_title": "Hello"}},
headers={"Idempotency-Key": "comment.created:c_981"},
timeout=10,
)
if res.status_code == 429:
print("retry after", res.headers["Retry-After"])
res.raise_for_status()
print(res.json()["id"], res.json()["skipped"])
# A recipient token for your frontend.
token = session.post(f"{BASE}/recipient-tokens", json={"recipient": "user_123"}, timeout=10).json()["token"]package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
)
func main() {
base := "https://api.notify.productcraft.co/v1/workspaces/" + os.Getenv("PRODUCTCRAFT_WORKSPACE_ID")
body, _ := json.Marshal(map[string]any{
"type": "comment.created",
"recipients": []string{"user_123"},
"data": map[string]string{"author": "Grace", "post_title": "Hello"},
})
req, _ := http.NewRequest("POST", base+"/notifications", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("PRODUCTCRAFT_API_KEY"))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", "comment.created:c_981")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err) // retry later with the same Idempotency-Key
}
defer res.Body.Close()
var out struct {
ID string `json:"id"`
Skipped []struct {
ExternalID string `json:"external_id"`
Reason string `json:"reason"`
} `json:"skipped"`
Code string `json:"code"` // on errors: e.g. NOTIFICATION_TYPE_NOT_FOUND
}
json.NewDecoder(res.Body).Decode(&out)
fmt.Println(res.StatusCode, out.ID, out.Skipped, out.Code)
}require "net/http"
require "json"
base = URI("https://api.notify.productcraft.co/v1/workspaces/#{ENV.fetch("PRODUCTCRAFT_WORKSPACE_ID")}/notifications")
req = Net::HTTP::Post.new(base)
req["Authorization"] = "Bearer #{ENV.fetch("PRODUCTCRAFT_API_KEY")}"
req["Content-Type"] = "application/json"
req["Idempotency-Key"] = "comment.created:c_981"
req.body = { type: "comment.created", recipients: ["user_123"], data: { author: "Grace", post_title: "Hello" } }.to_json
res = Net::HTTP.start(base.host, base.port, use_ssl: true) { |http| http.request(req) }
body = JSON.parse(res.body)
raise "#{res.code} #{body["code"]}: #{body["message"]}" unless res.code == "202"
puts body["id"], body["skipped"].inspect2
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.
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" }'3
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.
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"}4
Errors, retries and webhooks
- Errors are one JSON shape for every ProductCraft API:
{status_code, code, message, request_id, errors, details?}. Branch oncode; see error codes. - Retry network errors,
429(afterRetry-Afterseconds) and5xxwith the same Idempotency-Key. Do not retry other4xx. - Webhooks use Standard Webhooks signatures, so the
standardwebhookslibrary 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.