API Reference

SendPromptly API (Ingestion)

Base path: /api/v1/ (e.g., https://api.sendpromptly.example/api/v1/events)

Authentication

  • Use environment tokens in the Authorization header: Authorization: Bearer <ENV_TOKEN>.
  • Missing or invalid token returns 401 with a JSON error payload.

Important headers

  • Authorization: Bearer <ENV_TOKEN> — environment token (required)
  • Idempotency-Key: <uuid> — required for POST requests; must be a UUID. Missing header returns 400 with idempotency_key_required.
  • Content-Type: application/json
  • Optional tracing header: X-Request-ID for correlation in logs.

Idempotency

  • Idempotency keys are required for POST /events. Keys must be UUIDs and are retained for 24 hours (TTL).
  • Behavior:
    • Same key + same request fingerprint → replay returns the original stored response.
    • Same key + different fingerprint → 409 idempotency conflict.
    • Expired key (after 24h) → treated as a new request.

Fingerprinting: request body is SHA-256 hashed for comparison.

Endpoints (high level)

  • POST /api/v1/events — ingest an event (creates message and delivery_runs). Returns 201 on success with message_id and delivery_runs.
  • OPTIONS /api/v1/events — preflight
  • GET /api/v1/messages/{messageId} — message details
  • POST /api/v1/messages/{messageId}/replay — replay deliveries for a message

Errors & status codes

  • 201 Created — successful ingestion
  • 400 Bad Request — missing Idempotency-Key or malformed key
  • 401 Unauthorized — missing/invalid Authorization
  • 409 Conflict — idempotency conflict (same key, different body)
  • 422 Unprocessable Entity — validation errors (response includes details)
  • 429 Too Many Requests — rate limiting (may include Retry-After header)
  • 500 Internal Server Error — server error

Rate limits, quota & middleware order

The API pipeline enforces environment resolution, idempotency, hard quota/payment access, and rate limiting in this order:

ResolveEnvironmentFromToken → EnforceIdempotency → EnforceHardQuota → EnforcePaymentAccess → EnforceRateLimit

Quotas are enforced before dispatching deliveries; rate limit responses may include Retry-After (seconds).

Example: ingest event

curl -X POST "https://api.sendpromptly.example/api/v1/events" \
  -H "Authorization: Bearer ${ENV_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${UUID}" \
  -d '{
    "event_key": "user.signup",
    "payload": {"name":"Alice","occurred_at":"2026-02-01T12:00:00Z"},
    "recipient": {"email":"[email protected]"}
  }'

See linked sections for full field schemas, response shapes, and examples.