Velt REST APIs Best Practices
Comprehensive guide for Velt REST API v2, JWT authentication, and webhooks. Contains 12 rules across 4 categories covering core setup, REST API endpoints, webhook handling, and debugging.
When to Apply
Reference these guidelines when:
- Calling Velt REST API v2 endpoints from your backend
- Generating JWT tokens for frontend user authentication
- Handling Velt webhook events (comments, huddles, CRDT)
- Managing users, documents, organizations, or folders server-side
- Implementing GDPR data export or deletion
Rule Categories by Priority
| Priority |
Category |
Impact |
Prefix |
| 1 |
Core Setup |
CRITICAL |
core- |
| 2 |
REST API |
HIGH |
rest- |
| 3 |
Webhooks |
MEDIUM |
webhooks- |
| 4 |
Debugging |
LOW-MEDIUM |
debug- |
Quick Reference
Core Setup (CRITICAL)
core-rest-api-auth — x-velt-api-key + x-velt-auth-token headers for all REST callscore-jwt-tokens — Generate JWT tokens for frontend auth, 48h expiry, refresh flow
REST API (HIGH)
rest-comments — Comment annotation + comment CRUD endpointsrest-users — Add/get/update/delete users, GDPR data operationsrest-documents-orgs — Document, organization, folder managementrest-notifications — Notification add/get/update/delete + configrest-activities-crdt — Activity logs + CRDT data endpointsrest-advanced-webhooks — Manage advanced webhooks: config enable + endpoint CRUD + signing-secret retrievalrest-agents — List agent execution history with pagination and status filtersrest-memory — Memory judgments, knowledge ingestion/search, Q&A, suggestions, insights, and alertsrest-approval-engine — pointer (Approval Engine is now its own skill: see velt-approval-engine-best-practices)
Webhooks (MEDIUM)
webhooks-basic — v1 setup, event types, payload format, securitywebhooks-advanced — v2/Svix enterprise webhooks, retries, transformations
Debugging (LOW-MEDIUM)
debug-common-issues — Troubleshooting backend integration issues
Compiled Documents
AGENTS.md — Compressed index of all rules with file paths (start here)AGENTS.full.md — Full verbose guide with all rules expanded inline
1---2name: velt-rest-apis-best-practices3description: Velt REST API v2 and webhook best practices for server-side integration. Use when calling Velt REST API v2 endpoints, generating JWT tokens for frontend authentication, handling Velt webhooks (comment events, huddle events, CRDT updates), managing users/documents/organizations via REST, or implementing server-side Velt operations. Triggers on any task involving Velt REST API, JWT token generation for Velt, Velt webhooks, x-velt-api-key headers, or server-side comment/notification/activity management — even if the user doesn't explicitly say 'REST API'. For the Python SDK (velt-py) for self-hosting, see velt-self-hosting-data-best-practices instead.4license: MIT5---67# Velt REST APIs Best Practices89Comprehensive guide for Velt REST API v2, JWT authentication, and webhooks. Contains 12 rules across 4 categories covering core setup, REST API endpoints, webhook handling, and debugging.1011## When to Apply1213Reference these guidelines when:14- Calling Velt REST API v2 endpoints from your backend15- Generating JWT tokens for frontend user authentication16- Handling Velt webhook events (comments, huddles, CRDT)17- Managing users, documents, organizations, or folders server-side18- Implementing GDPR data export or deletion1920## Rule Categories by Priority2122| Priority | Category | Impact | Prefix |23|----------|----------|--------|--------|24| 1 | Core Setup | CRITICAL | `core-` |25| 2 | REST API | HIGH | `rest-` |26| 3 | Webhooks | MEDIUM | `webhooks-` |27| 4 | Debugging | LOW-MEDIUM | `debug-` |2829## Quick Reference3031### Core Setup (CRITICAL)32- `core-rest-api-auth` — x-velt-api-key + x-velt-auth-token headers for all REST calls33- `core-jwt-tokens` — Generate JWT tokens for frontend auth, 48h expiry, refresh flow3435### REST API (HIGH)36- `rest-comments` — Comment annotation + comment CRUD endpoints37- `rest-users` — Add/get/update/delete users, GDPR data operations38- `rest-documents-orgs` — Document, organization, folder management39- `rest-notifications` — Notification add/get/update/delete + config40- `rest-activities-crdt` — Activity logs + CRDT data endpoints41- `rest-advanced-webhooks` — Manage advanced webhooks: config enable + endpoint CRUD + signing-secret retrieval42- `rest-agents` — List agent execution history with pagination and status filters43- `rest-memory` — Memory judgments, knowledge ingestion/search, Q&A, suggestions, insights, and alerts44- `rest-approval-engine` — pointer (Approval Engine is now its own skill: see `velt-approval-engine-best-practices`)4546### Webhooks (MEDIUM)47- `webhooks-basic` — v1 setup, event types, payload format, security48- `webhooks-advanced` — v2/Svix enterprise webhooks, retries, transformations4950### Debugging (LOW-MEDIUM)51- `debug-common-issues` — Troubleshooting backend integration issues5253## Compiled Documents5455- `AGENTS.md` — Compressed index of all rules with file paths (start here)56- `AGENTS.full.md` — Full verbose guide with all rules expanded inline
velt-js