Loading ...

REST API Overview | Axero Documentation

Home » axero documentation » Wiki » Documentation » REST API Overview
Axero Documentation  Wiki
Public Space
Activity Stream Content
Version 149

REST API Overview

4.72 
 /5
4.72 (1votes)

The Axero REST API lets your own code read and change the data on your Axero site. Use it to sync user data, build custom dashboards, or connect Axero to other systems.

Before You Call Anything

Five things hold across the whole API. Each endpoint page repeats the ones that apply to it; this is the one place they sit together.

Authentication

  • Send your Bearer token on every request as Authorization: Bearer YOUR_TOKEN. Creating Bearer Tokens covers issuing, renaming, and revoking one, and Enabling API Access covers the administrator side.
  • The same token is also accepted in a Rest-Api-Key header, which is how older integrations send it. New integrations should use the Authorization header.
  • Never put a token in a widget, a page, or any code that runs in a visitor's browser. Inside your Axero site, leave the header off and the call runs as the signed-in user.

Response shape

  • Most endpoints answer 200 with an envelope, a standard wrapper around the result: {"IsError": false, "ResponseMessage": "", "ResponseData": ...}. A refused or failed request is often also a 200. Some set IsError true and put the reason in ResponseMessage. But a 200 with IsError false is not proof the request matched anything. An ID that matches nothing can answer IsError false with "Content not found." in ResponseMessage and no ResponseData. A filter value an endpoint does not recognize can also be ignored without an error. Check that ResponseData holds what you asked for, and read ResponseMessage when it does not.
  • A few families return their value directly with no envelope: the Journeys endpoints, the Page Builder list and HTML calls, and a handful of user checks such as the two-factor status and RSVP status. Their pages say so.

Paging

  • List endpoints take StartPage (starting at 1) and PageLength, and return TotalRecords beside the list. Defaults differ by endpoint and are stated on each page.

Request rate

  • There is no hard limit by default, except on the routes that run an Axero Function, which enforce their own per-caller and site-wide limits. Keep to 5 calls per second, no more than 3 in flight at once, and expect a response within 15 seconds. Axero may throttle an integration that affects the site.

Status codes

  • 401: the token is missing, expired, or revoked. 403: the token's user lacks the permission the endpoint checks.
  • 404 with "No HTTP resource was found" usually means a required query parameter was left out and no route matched, not that the object is missing. 405 means the wrong verb. It can also mean a query-string parameter was left out, or sent in the request body instead, so no route matched.
  • 400 and 500 are rarer than the 200-with-IsError case above; each endpoint page lists the statuses it actually returns.

Worked examples in curl, JavaScript, and Python are on Using the REST API.

Getting Started

Prerequisites

Before you use the Axero REST API, you need the following:

  1. Administrator Setup: An administrator must enable REST API access and configure security settings for your organization
  2. User Permissions: Your user role must have REST API permissions enabled by an administrator
  3. Authentication: You need a valid Bearer token for API authentication
  4. Development Environment: A tool for making HTTP requests (Postman, curl, or your preferred programming language)

Quick Start Guide

Starting with Axero version 9.45, the REST API uses Bearer tokens for authentication instead of the older API keys. Each token has its own name and expiration date, and you can revoke one without affecting the others.

Get started:

  1. Verify API access is enabled: Enable REST API Access
  2. Create your token: Create Bearer token
  3. Test your first API call: 
    curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://your-site.axero.com/api/users/me
  4. Explore the API Categories below to find the endpoints you need

For detailed usage guidelines and best practices: See Using the REST API

API Categories

The endpoints are grouped by what they work on. The main categories are below, and each one links to its own overview page.

Users API

Create, update, and look up user accounts, and manage their roles.

Key Features

  • Retrieve user profiles and account information
  • Create and manage user accounts
  • Assign and update user roles and permissions
  • Search and filter users by various criteria
  • Manage user membership in spaces
  • Update user points and recognition metrics

Common Use Cases

  • User Synchronization: Import users from existing HR systems or databases
  • Automated Onboarding: Create user accounts when new employees join
  • Role Management: Update user roles when employees change positions
  • Directory Integration: Sync user information with Active Directory or LDAP
Documentation: REST API: Users 

Content API

Create, read, and manage articles, blogs, wikis, files, and other content.

Key Features

  • Create and publish articles, blog posts, and other content types
  • Retrieve content lists with filtering and sorting options
  • Manage content categories and tags
  • Handle file uploads and attachments
  • Access workflow and approval queues
  • Manage content permissions and visibility

Common Use Cases

  • Content Syndication: Display community content on external websites or digital signage
  • Automated Publishing: Create content from external systems or feeds
  • Content Migration: Import existing content from other platforms
  • Custom Dashboards: Build personalized content views and recommendations
Documentation: REST API: Content 

Spaces API

Create and manage the spaces that organize your community into departments, teams, or projects.

Key Features

  • Create and configure new spaces
  • Retrieve space information and metadata
  • Manage space membership and access controls
  • Assign and update space-specific roles
  • Configure space settings and permissions
  • Organize spaces in hierarchical structures

Common Use Cases

  • Organizational Structure: Mirror your company's department structure in digital spaces
  • Project Management: Create temporary spaces for specific projects or initiatives
  • Access Control: Manage who can access sensitive or department-specific information
  • Automated Provisioning: Create spaces automatically based on external triggers
Documentation: REST API: Spaces 

Chat API

Send and read chat messages from another system.

Key Features

  • Send and receive chat messages
  • Create and manage chat threads
  • Add participants to conversations
  • Retrieve message history and thread information
  • Mark messages as read, mark threads as favorites, and set your online chat status

Common Use Cases

  • Workflow Integration: Trigger chat notifications from external systems
  • Customer Support: Route support requests to appropriate chat channels
  • Automated Messaging: Send system notifications or reminders via chat
  • Cross-Platform Communication: Relay conversations between Axero chat and other systems
Documentation: REST API: Chat 

Comments API

Create, read, and moderate comments on any type of content.

Key Features

  • Create and post comments on content
  • Retrieve comment threads and individual comments
  • Edit and update existing comments
  • Delete comments and manage moderation
  • Set comment status and approval workflows
  • Add and list attachments on a comment

Common Use Cases

  • Feedback Collection: Gather input and opinions on proposals or ideas
  • Moderation Automation: Implement automated comment filtering and approval
  • Engagement Analytics: Track discussion patterns and user engagement
  • Content Enhancement: Post updates or extra details on content as comments
Documentation: REST API: Comments 

Permissions API

Check and change what users and roles are allowed to do.

Key Features

  • Check user permissions for specific actions or content
  • Update role permissions and access levels
  • Validate access rights before performing operations
  • Manage permission inheritance and overrides
  • Check which permissions a role holds, not only a user

Common Use Cases

  • Access Validation: Verify user permissions before displaying content or features
  • Role Management: Programmatically update permissions when organizational roles change
  • Security Auditing: Review which roles hold a permission in a space
  • Custom Authorization: Apply Axero permissions inside external applications
Documentation: REST API: Permissions 

Workflows API

Set up the approval workflows that content passes through before it is published, with each approval step assigned to a role, in one space or at site level.

Key Features

  • List workflows across every space, or filter by space, content type, or status
  • Read one workflow with its steps in approval order
  • Create a workflow and its steps in one request
  • Replace a workflow's name, description, status, and steps in one request
  • Add, reassign, move, or remove a single approval step
  • Delete a workflow that is not the default and has no content waiting for approval

Common Use Cases

  • Approval Auditing: Review which spaces require approval and which roles approve at each step
  • Automated Provisioning: Create a space's approval workflow from another system when the space is set up
  • Bulk Updates: Reassign an approval step to a different role across many workflows at once
Documentation: REST API: Workflows 

Recognition API

Award recognition, and read programs, badges, challenges, and leaderboards.

Key Features

  • Award badges and recognition to users
  • Retrieve recognition programs and available badges
  • Access challenge and leaderboard data
  • Get user-specific recognition insights and achievements
  • List the recognition programs a user belongs to

Common Use Cases

  • External Integration: Award recognition when users complete tasks in other systems
  • Performance Tracking: Integrate recognition data with HR or performance management systems
  • Automated Recognition: Trigger awards based on specific behaviors or milestones
  • Gamification: Build custom leaderboards and achievement systems
Documentation: REST API: Recognition 

Analytics API

Read engagement and content performance figures for your community.

Key Features

  • Retrieve content engagement metrics and analytics
  • Access user activity and participation data
  • Get space-specific analytics and usage patterns
  • Track trending content and popular topics
  • Monitor community health and engagement metrics

Common Use Cases

  • Custom Dashboards: Build executive dashboards with community metrics
  • Content Strategy: Identify trending topics and high-performing content
  • User Engagement: Track and reward the most active community members
  • ROI Reporting: Feed community activity figures into your own return-on-investment reports
Documentation: REST API: Analytics 

The API has more categories than the nine above. Each has its own overview page listing every endpoint: REST API: Administration, REST API: Cases, REST API: Engagement, REST API: Events, REST API: Files, REST API: Forums, REST API: Notifications, REST API: Personas, REST API: Polls and Surveys, REST API: Roles and Permissions, REST API: Tags, REST API: Tasks, REST API: Wall Posts, REST API: Axero Copilot, REST API: Journeys.

Next Steps

Take these steps in order:

1. Set Up Authentication

Create your Bearer token and make one test call, such as the one in the Quick Start Guide above

2. Test Your Integration

Start with simple API calls to verify your setup and understand responses

3. Build Your Solution

Build your integration, keeping to the request rate under Before You Call Anything

4. Monitor & Optimize

Log each call's status code and IsError value, so a failed request shows up before a person notices it

Wiki Index

Pages