Zapnito API overview

The API lets your systems read and manage data in your Zapnito community, such as users, groups, organisations, content and badges. Every request goes to your community’s domain and is authenticated with an API token.

To be notified when something happens in your community instead of polling for changes, use webhooks.

How it works

Send your API token

Include your API token in the Authorization header of every request.

Validate your key

Send a GET request to the ping endpoint to confirm Zapnito accepts your token.

Call an endpoint

Pick a resource from the resources list and send a request to it.

Base URL

All endpoints live under /api/v1 on your community’s domain:

https://your-community.zapnito.com/api/v1

Replace https://your-community.zapnito.com with your community’s domain.

Authentication

Authenticate every request by sending your API token in the Authorization header:

Authorization: Token token=YOUR_API_TOKEN

A request with a missing, invalid or expired token is rejected with 401 Unauthorized.

Validate your API key

Send a GET request to the ping endpoint with no other parameters to check that your token is valid.

Validate your API key

curl "https://your-community.zapnito.com/api/v1/ping" \
  -H "Authorization: Token token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8"

GET https://your-community.zapnito.com/api/v1/ping

{
  "message": "Nice one, your API key is valid"
}

HTTP Token: Access denied.

200 OK: the API key is valid.
401 Unauthorized: the API key is rejected.

Request headers

Send these headers with every request.

Header	Value	Notes
`Authorization`	`Token token=YOUR_API_TOKEN`	Required.
`Content-Type`	`application/json; charset=utf-8`	Required. Request bodies are JSON.

Pagination

List endpoints return results a page at a time. Where an endpoint supports pagination, it accepts these query parameters:

Parameter	Type	Description
`page`	integer	The page of results to return.
`per_page`	integer	The number of results to return per page.

Responses and errors

Zapnito uses standard HTTP status codes. The codes you’re most likely to meet are:

Status	Meaning
`200 OK`	The request succeeded. Some endpoints also return `200 OK` when there was nothing to change, such as adding a user who is already in a group.
`201 Created`	The request created a record.
`401 Unauthorized`	Your API token is missing, invalid, expired or badly formatted.
`403 Forbidden`	The account making the request doesn’t have permission to do this.
`404 Not Found`	No record matches the ID, slug, UUID or email address in the request.
`409 Conflict`	The record you’re creating already exists.
`422 Unprocessable Entity`	A required parameter is missing or invalid. The response lists the problems under `errors`, keyed by parameter name.

Error response formats aren’t yet consistent across endpoints. Some return a JSON object with an errors key, and others return a plain text message. Check the endpoint page for the response you’re handling.

Resources

Resource	Use it to
Users	Find users and update their profile details.
Invitations	Send invitation emails and place invitees in a group.
Groups	Create groups.
Group users	Search a group’s users, and add or remove users.
Organisations	List, create and update organisations.
Organisation users	Add or remove users in an organisation.
Content	List, view, publish, unpublish and schedule content.
Tags	Find and create tags.
Tag content	Assign content to a tag.
Third-party resources	Manage links to resources held in your external systems.
Channels	List the channels in your community.
Channel content	List the content in a channel.
Rooms	List, view and create rooms.
Badges	List, create, update and delete badges.
Badge assignments	Assign badges to content and users, or remove them.

Getting started

Users

Groups and organisations

Content

Channels and rooms

Badges

How it works

Base URL

Authentication

Validate your API key

Request headers

Responses and errors

Resources

​How it works

​Base URL

​Authentication

​Validate your API key

​Request headers

​Pagination

​Responses and errors

​Resources

How it works

Base URL

Authentication

Validate your API key

Request headers

Pagination

Responses and errors

Resources