velt-rest-apis-best-practices

Implement Velt REST API v2 calls, JWT authentication, and webhook handling server-side.

1|Updated Jan 23, 2026
One-click install
npx skills add https://github.com/velt-js/agent-skills --skill velt-rest-apis-best-practices-velt-js
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: velt-rest-apis-best-practices
Source: https://github.com/velt-js/agent-skills/tree/main/skills/velt-rest-apis-best-practices
Command: npx skills add https://github.com/velt-js/agent-skills --skill velt-rest-apis-best-practices-velt-js

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Server-side Velt integrations fail with 401 errors, expired tokens, and webhook signature mismatches when developers miss the required header contract, generate JWTs on the client, or bind to outdated response shapes. This Skill provides verified rules for every Velt REST API v2 endpoint, JWT token flow, and webhook version. ## Core Features & Use Cases - Authentication Contract: Enforces the correct header pair for every call — x-velt-api-key + x-velt-auth-token for api-key-level endpoints, x-velt-workspace-id + x-velt-workspace-auth-token for workspace-level endpoints — plus server-side JWT generation with 48-hour expiry and refresh handling. - Full REST CRUD Coverage: Documents request and response shapes for comment annotations, comments, users (including GDPR export/delete), documents, organizations, folders, notifications, activity logs, CRDT data, agent executions, and Memory endpoints. - Webhook Management: Covers v1 webhook setup, v2/Svix enterprise webhooks with retries and signature verification, and programmatic advanced-webhook endpoint management with signing secrets. - Use Case: When building a Next.js backend that provisions Velt documents, generates JWT tokens for frontend users, and receives comment webhooks, the agent applies these rules to produce correct endpoint paths, headers, and payload envelopes on the first attempt. ## Quick Start Ask the agent to generate a server-side Next.js API route that creates a Velt JWT token for a user and lists comment annotations for a document using the REST API v2.

Frequently Asked Questions about velt-rest-apis-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I authenticate Velt REST API v2 calls?▼

Every Velt REST API v2 call requires two headers: x-velt-api-key and x-velt-auth-token for api-key-level endpoints, or x-velt-workspace-id and x-velt-workspace-auth-token for workspace-level endpoints. All endpoints use POST with a { data: {...} } body wrapper.

How do I generate JWT tokens for Velt frontend authentication?▼

Generate JWT tokens server-side via POST https://api.velt.dev/v2/auth/token/get with your API key and auth token, never from client code. Tokens expire after 48 hours; listen for the token_expired event on the frontend and call your backend to refresh.

Why does my Velt REST API call return 401 Unauthorized?▼

A 401 means missing or mismatched authentication headers. Verify both x-velt-api-key and x-velt-auth-token are present, and confirm you are not sending the api-key-level pair to a workspace-level endpoint such as /v2/workspace/get.

Does the Velt REST API support GET or DELETE methods?▼

No. All Velt REST API v2 endpoints use POST, including read and delete operations. Using GET or DELETE will fail; pass identifiers in the { data: {...} } request body instead.

How do I verify Velt webhook signatures?▼

For v2/Svix advanced webhooks, fetch the server-generated signing secret via POST /v2/workspace/advancedwebhook/endpoints/secret/get and use it to verify delivered payload signatures. Never pass your own secret when creating an endpoint; it is always generated server-side.

When should I use the velt-py Python SDK instead of the REST API?▼

Use the velt-py Python SDK when self-hosting Velt data on your own infrastructure with custom data providers. That scenario is covered by the velt-self-hosting-data-best-practices skill; this skill covers Velt's hosted REST API v2 surface.