Looking for the APIv2 swagger reference? You can find it in you dashboard in the APIv2 section, or in our full API reference. Note that the reference in the dashboard will always be more accurate to what is available on your site than the full reference.
Overview
We've rebuilt Vanilla's API from the ground up to enable tighter integrations and lower-level access to all of Vanilla's features using an API-first strategy. The initial release will provide feature parity with our API v1. New endpoints will become available as they are completed, so watch for new product announcements in our release notes.
Looking for APIv1 docs?
Key improvements in API v2
- More authentication options, including per-user access tokens.
- Complete, custom API docs in your dashboard, including examples you can use immediately.
- More endpoints so you can control more of your site from the API.
- Cross-origin resource sharing (CORS) support.
- Greater functional consistency, and higher conformance to current industry best practices.
- Better automated testing, to reduce regression bugs and unwanted changes.
Pagination
We use 2 types of pagination in the API:
- Numbered pagination
- Used where possible.
- Have access to first, last, previous and next pages.
- More pagination
- Used where querying the totals of a particular resource would not be performant.
- Have access to first, previous and next pages.
Resources that support pagination have page and limit parameters. For example: /api/v2/{RESOURCE}?page={PAGE_NUM}&limit={NUM_ITEMS}
Since the API returns an array of records, the paging information is sent using the Link header.
Link header example:
Link: <https://forum.example.com/api/v2/users?page=1&limit=100>; rel="first",
<https://forum.example.com/api/v2/users?page=5&limit=100>; rel="next"
The example includes a line breaks for readability.
Depending on the pagination type, the following rel values are possible:
firstThe link relation for the first page of records.lastThe link relation for the last page of records.prevThe link relation for the immediate previous page of records. Only available if page > 1.nextThe link relation for the immediate next page of records. Only available if more records are available.
Note: Results per pages can be lower than limit even if more pages are available. This is due to rows being removed based on the current user's permissions. It is also possible to have empty pages for the same reason. The Paging-Next header will always be present when more rows are available.