Use this guide when planning a server-to-server integration with Vanilla API v2. It covers:
- common implementation patterns,
- authentication choices,
- endpoint lookups,
- pagination,
- webhooks, and
- situations where you may need more than one API call.
Before you begin…
Vanilla API v2 endpoint availability, request parameters, response fields, and webhook events can vary by community configuration and enabled addons.
NOTE: For the most accurate reference, check your own Dashboard at:
Settings > API Integrations > API V2
The Dashboard reference is tailored to your community, and is more accurate than the general reference.
Recommended integration pattern
For most server-to-server integrations, use a dedicated integration account and a Personal Access Token.
- Create or choose a dedicated Vanilla user account for the integration.
- Assign only the Roles and permissions the integration needs.
- Confirm the Role has the following permission:
Garden > Tokens > Add. - From that user's profile, navigate to the Personal Access Tokens page (click Access Tokens in the page list on the right) and click Generate New Token.
- Store the token securely in your integration platform or secret store.
- Send the token in the
Authorization header:
Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN
IMPORTANT: Personal Access Tokens are intended for server-to-server integrations and should not be exposed in HTML, JavaScript, mobile apps, or public pages. API calls made with a token reflect the permissions of the user who generated it.
Access Tokens do not have expiration dates. You can manually rotate them based on your organizations security policy.
Start with a smoke test
Before building a full integration, test the connection with:
GET /api/v2/users/me
A successful response confirms that your:
- integration can reach Vanilla,
- the token is valid,
- the token has API access, and
- your client can receive JSON responses.
API, webhooks, or both?
- Use API calls when your integration needs to fetch records on demand, retrieve filtered datasets, paginate through results, enrich another workflow, or perform controlled write/update operations.
- Use webhooks when your integration needs to react to events such as a new user registration, profile update, new discussion or comment, reaction, accepted answer, badge, rank, or point event.
- Use a hybrid pattern when a webhook tells your system that something happened, but your system needs to call the API afterward for more detail.
Recipe: Query records by known names or external IDs
When supported, use Smart IDs to look up records without first resolving the numeric Vanilla ID. Smart IDs can be used in paths, queries, and request bodies.
Examples:
GET /api/v2/users/$name:alex
GET /api/v2/categories/$urlcode:support-qna
GET /api/v2/discussions?categoryID=$name:Help
When using Smart IDs in real requests, URL-encode them as needed.
Recipe: Retrieve discussions across categories
If you need discussions from a parent category and its child categories, confirm the available category and discussion parameters in your site’s API v2 reference.
Typical approach:
- Retrieve the relevant parent category.
- Retrieve or identify the child category IDs.
- Query discussions for each category as needed.
- Combine and deduplicate results in your integration.
This is often more reliable than assuming one endpoint will automatically return every nested category’s discussions.
Recipe: Handle user-specific discussion data
Some discussion response fields may reflect the authenticated API user. For example, bookmark state is tied to the caller whose token is used.
If your integration needs user-specific state for many users, do not assume one admin-token request will represent every member’s view. You may need a design that separately retrieves caller-specific data, uses spoofing where appropriate, or merges API results client-side.
Spoofing API calls is available for server-side integrations, but it requires an admin-capable token and should be used cautiously. Spoofed calls are limited by the permissions of the user being spoofed.
To spoof another user you will need to have an Access Token that has the same or higher permissions than the user being spoofed. Add this special header to the request:
X-Vanilla-Spoof: <userID>.
Don’t forget, you can use SmartID here too:
X-Vanilla-Spoof: $email:<userEmail>.
Recipe: Find status or subscription history
For history-style questions, first check whether the relevant history endpoint or analytics data source exists in your site’s API reference.
Common examples:
Question | Where to check first |
|---|
“How did an idea’s status change over time?” | Discussion status-log endpoints in your Dashboard API reference |
“Can I get category follow/unfollow activity?” | Analytics or subscription-change data sources |
“Is there a webhook for this exact event?” | Webhooks page in your Dashboard and the Webhooks KB article |
If an event is not available as a webhook, use an API or analytics export pattern instead.
Recipe: Export large datasets
Some API calls can be exported as CSV by adding .csv to the endpoint path. For example:
GET /api/v2/users.csv?page=1&limit=5000
CSV export behavior can differ from standard JSON API limits, so confirm the endpoint’s supported limits and pagination behavior before building a bulk export.
Pagination and rate limits
API resources that support pagination generally use page and limit parameters, with paging information returned in the Link header.
Vanilla API requests are rate-limited per IP:
Request type | Limit |
|---|
GET | 300 requests per 1 minute |
POST, PUT, PATCH, DELETE | 120 requests per 1 minute |
Hard limit | More than 250 requests in 10 seconds may require Support intervention |
If you exceed limits, the API returns HTTP 429 Too Many Requests.
The temporary block typically lifts after 1 minute.
Troubleshooting checklist
Symptom | Check |
|---|
401 or 403 response | Token validity, token owner permissions, endpoint permissions |
Missing fields | Your site-specific API reference, enabled addons, authenticated user context |
Empty results | Category permissions, filters, date ranges, pagination |
Works for admin but not integration user | Role permissions assigned to the token owner |
Browser-side request fails | Do not expose PATs client-side; use a server-side integration |
Too many requests (429 response) | Add batching, pagination delays, backoff, or scheduled sync windows |
Need another user’s perspective | Consider whether spoofing is appropriate and safe |