This article serves as an easy-to-understand, step-by-step guide to exploring and using your community's built-in API — no coding experience required.
What this guide covers
Your community platform comes with a powerful Application Programming Interface (API) for viewing and manipulating raw data. Your Vanilla Dashboard has an Interactive API Help page that gives you hands-on access to the API. Think of it as a control panel that lets you read and change information in your community, such as members, discussions, categories, roles, and much more, without clicking through the Dashboard one screen at a time.
The good news is you don't need to be a developer to start using it. Your site includes a built-in API Docs page that lists everything the API can do and lets you try it out safely, right in your browser. This guide walks you through how to do this from start to finish.
IMPORTANT: Before you begin, you'll want to be signed in to your community with an administrator account. The API can change
real data on your live site, so read the Safety tips & best practices section before running anything other than a simple lookup.
Understanding the API and the API Docs page
What is an API, really?
An API is simply a way for one piece of software to ask another for information, or to perform an action, using a predictable set of requests. Every time you load a page in your community, your browser is quietly making API requests behind the scenes.
The API lets you make those same requests directly. For example, you could ask the API to:
- “Give me a list of the 30 newest members”
- “Show me every discussion in the Announcements category”
- “Change this member's role to Moderator”
- “Close this discussion”
What is the API Docs page?
The API Docs page is an interactive catalog, built into your Dashboard, of every request the API understands. For each request, it tells you what it does, what information you can send it, and what it will send back. Best of all, it has a Try It feature that lets you run a real request and see the real result, all without writing a single line of code.
TIP: Community managers love it because It's the fastest way to pull a quick report, bulk-check data, or preview exactly what a request does
before asking a developer to automate it.
Who can use it & how to open it
Permissions
The API Docs page is an administrative tool. You'll only see it if your account has permission to manage the site. Any request you run from the page is performed as you — so you can only do things your own account is already allowed to do. If you can't see the page, ask a site administrator to grant you the appropriate access.
Access the page
- Log in to your community with your administrator account.
- Access the Dashboard. This is the administrative area of your site (usually reached from your avatar menu or by adding
/dashboard to your site address). - Navigate to Settings > API Integrations > API v2. (You can also reach it directly by adding
/settings/api-docs to your site address.)
What you'll see at the top
The page is titled Vanilla API v2 and shows your API's base web address (it ends in /api/v2).
Every request on the page starts from that address.
Finding your way around the page
The page is organized into categories listed alphabetically, including Discussions, Users, Categories, and Roles. Each category groups together all the requests related to that topic.
Expanding a category
Each category starts collapsed, showing an Endpoint Summary, or compact list of its requests.
Click Expand to reveal the full details of every request in that category, and click any single request in the summary to jump straight to it.
Reading the list
Every line in the list has two parts:
- A colored action label (GET, POST, PATCH, or DELETE) — explained in the next section.
- A path such as
/discussions or /users/{id}. This is the specific thing you're acting on. A part in curly braces like {id} is a placeholder you fill in — for example, the ID number of a specific discussion.
TIP: Hover over any request in the summary to see a short description of what it does before you open it.
Reading an endpoint: the four action types
Each request has a method (the colored label) that tells you what kind of action it
performs. This is the single most important thing to understand before running anything.
TIP: If you're exploring or learning, stick to GET requests. They never alter your community.
Only use POST, PATCH, and DELETE when you're certain of what you're doing, because they immediately change real data on your live site.
The three kinds of information a request may need
When you open a request, you may be asked to provide up to three types of input:
- Path parameters: Values built into the address, such as the
{id} of the specific item you want. Required whenever the path has a placeholder. - Query parameters: Optional filters and settings, such as how many results to return, which page, or how to sort them.
- Request Body: The actual content you're sending in, used by POST and PATCH (for example, the title and text of a new discussion).
Making a live call with “Try It”
Let's run a real, safe request: fetching a list of recent discussions.
- Find the request. Scroll to the Discussions category, click Expand, and locate
GET /discussions. - Click this request to view it. Click the Try It button next to it. A large window opens with two sides: your request on the left and the response on the right.
- Fill in what you need. For this request everything is optional. In Query Parameters, you might set a limit (for example, 10) to keep the list short. If a box has a dropdown or a list of allowed values, use it rather than typing.
- When ready, click Send at the top right.
- Read the result on the right side. Refer to the next section for how to interpret it.
- Close the window when you're done, and try another request.
Filling in the request form
The window presents the request as a simple fill-in-the-blanks form, grouped into Path Parameters, Query Parameters, and Request Body. If a section says no parameters are supported, you can skip it. Required fields are listed first.
Form view vs. editor view
For requests that send a body (POST and PATCH), you can fill in the friendly form, or click Show Editor to type the raw data directly as text. Most community managers should stay in the form view; the editor is there for advanced users. You can switch back with Show Form, and Clear empties the body so you can start over.
NOTE: Calls you run here are performed under your own logged-in account, so you don't need to enter any password, key, or token to use the Try It feature. You only need a token for calls made from outside Vanilla (refer to the Calling the API from outside Vanilla section).
Understanding the response
After you click Send, the right side of the window fills in with what the API sent back. It has three parts.
The status
A number that tells you whether the request succeeded. The most common ones:
Status | Meaning |
|---|
200 / 201 | Success. (201 usually means something new was created.) |
400 | Something in your request was invalid - check your inputs. |
403 | You don't have permission to do this. |
404 | The item wasn't found - check the ID you entered. |
429 | Too many requests too quickly — wait a moment and retry. |
500 | Something went wrong on the server's side. |
The response body
This is the actual data, shown as neatly formatted JSON — a structured text format that lists information as labelled fields. For a list of discussions, you'll see each discussion's title, author, date, and so on. You can read it directly, or copy it into a spreadsheet or document.
The response headers
A table of behind-the-scenes technical details about the response. You can usually ignore these, but they're occasionally useful when troubleshooting with a developer (for example, they show how close you are to a rate limit).
TIP: If you want to see the shape before sending, click Show Schema to preview the list of fields a response will contain, described in plain terms,
before you actually run the request.
Copying a call to share with a developer
Once you've built a request in the Try It window, you can hand it off to a developer or reuse it in another tool without rebuilding it. At the top of the window, click the Copy as… menu and choose a format:
Option | Use it when… |
|---|
Copy as CURL | You want to give a developer a ready-to-run command they can paste into a terminal. |
Copy as Fetch (JavaScript) | A developer wants to drop the request straight into website or app code. |
Copy as URL | You just want the plain web address of the request — handy for simple lookups you can paste into a browser or a spreadsheet. |
Whichever you pick, the request is copied to your clipboard exactly as you built it, including the parameters you filled in, so you can paste it wherever you need. The menu confirms with “Copied to Clipboard”.
NOTE: A copied command runs outside your logged-in browser session, so on its own it isn't signed in. To make it work elsewhere, it needs an access token (this process is covered next).
Calling the API from outside Vanilla
The Try It feature (discussed in the Making a live call with “Try It” section above) is perfect for one-off tasks. But if you (or a developer) want to run requests from another program, a spreadsheet tool, or a scheduled automation, you'll need a Personal Access Token.
What is a Personal Access Token?
A token is a long, secret string of characters that acts like a password for the API. It proves the request is coming from your account. Anyone who has your token can act as you, so treat it exactly like a password.
Creating a token
- Navigate to your community profile and click Access Tokens in the page list on the right. This opens the Personal Access Tokens page.
- Click Generate New Token.
- Give it a clear name, something describing what it's for, such as “Monthly member export.” This helps you recognize and manage it later.
- Click Generate.
- Click Reveal next to the new token to display the full secret value, and copy it somewhere safe immediately.
IMPORTANT: Store your token safely. Treat the token like a password. Don't email it, paste it into chat, or share it publicly. If a token is ever exposed or no longer needed, return to this page and click Delete to revoke it right away - any program using it will immediately stop working.
Using the token in a request
When making a request from another tool, include the token so the API knows it's you. The standard way is to add an authorization header:
For example, a complete command to fetch discussions from outside Vanilla looks like this:
This is exactly what the Copy as CURL option produces — you simply add your token to it.
Safety tips & best practices
- Explore with GET first. Reading data is always safe. Get comfortable with GET requests before touching anything that creates, updates, or deletes content on your live site.
- Double-check IDs before you change anything. A PATCH or DELETE targets the exact item in the path. Confirm you have the right
{id} by looking it up with a GET first. - Remember it's your live community. There is no separate “practice” area — changes take effect immediately for real members. If your organization has a staging or test site, test there first.
- Deletes can be permanent. Treat DELETE as irreversible, unless you know otherwise.
- Mind the rate limits. The API limits how many requests you can make in a short time. If you see a
429 status, simply pause and try again more slowly. - Secure your tokens. Name them clearly, never share them, and delete ones you no longer use.
- You can only do what your account can do. The API respects your existing permissions, so it won't let you bypass the limits of your role.
- When in doubt, ask. If a request involves bulk changes or anything you're unsure about, check with a developer or administrator before clicking Send.
TIP: A reliable workflow is to look it up with GET → confirm the IDs and inputs → make the change with POST / PATCH / DELETE → run the GET again to confirm the result.
Glossary & more help
Glossary
- API: A structured way for software to request
information or actions. - Endpoint: A single request the API understands, made of
a method plus a path. - Method: The action type: GET, POST, PATCH, or DELETE.
- Path: The part of the address identifying what you're acting on (e.g.
/users/{id}). - Parameter: A value you supply with a request (in the path,
as a filter, or in the body). - Body: The content you send when creating or updating something.
- JSON: The structured text format used for request bodies and responses.
- Status code: A number saying whether a request succeeded or why it failed.
- Access token: A secret key that identifies you when calling the API from outside the site.
- Rate limit: A cap on how many requests you may make in a given period.
Where to get more help