Skip to content

REST API Actions

Jump to bottom Edit New page
keenly edited this page Jan 5, 2017 · 33 revisions

This wiki is outdated and does not contain every feature (as they’re not documented), feel free to open an issue if you have any questions.

Table of Contents

Here’s a complete list of all the different actions and their response.

For these examples I’m using these the following values:

Username Contex
User Hash 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
API Key d8e8fca2dc0f896fd7cb4cb0031ba249

Summary of actions

Action Name Version Added Parameters Supported Summary Notes
authenticate 1.0 performance Authenticates the user and returns the hash that the user has to use for future requests
createAlert 1.4 performance Creates an alert for the specified user Missing documentation
createConversation 1.4 performance, grab_as Creates a conversation as the specified user Missing documentation
createConversationReply 1.4 performance, grab_as Creates a conversation reply as the specified user Missing documentation
createPost 1.4 performance, grab_as Creates a new post as the specified user Partial documentation
editPost ? performance, grab_as,post_id, thread_id, message Edit existing post Missing documentation
createProfilePost 1.4 performance, grab_as Creates a new profile post as the specified user Missing documentation
createProfilePostComment 1.4 performance, grab_as Creates a new profile post comment as the specified user Missing documentation
createThread 1.4 performance, grab_as, node_id, prefix_id, title, message Creates a new thread and first post as the specified user Missing documentation
editThread ? performance, grab_as, thread_id, node_id, prefix_id, title, discussion_open, sticky Edit existing thread Missing documentation
editUser 1.3 performance Edits a XenForo user
deletePost 1.4 performance Deletes a post as the specified user Missing documentation
getAddon 1.2 performance Returns any relevant information about the specified addon
getAddons 1.2 performance Returns a list of the installed addons
getActions 1.0 performance Returns a list of all the available actions and their permission levels
getAlerts 1.1 performance, grab_as Returns the alerts of the specified user
getAvatar 1.0 performance, grab_as Returns the avatar of the specified user
getConversation 1.4 performance Returns the specified conversation Missing documentation
getConversations 1.3 performance, limit, grab_as Returns the conversations of the specified user
getGroup 1.0 performance Returns any relevant information about the specified group
getNode 1.3.1 performance Returns any relevant information about the specified node
getNodes 1.3.1 performance, limit Returns a list of the nodes
getPost 1.3 performance, grab_as Returns any relevant information about the specified post
getPosts 1.3 performance, grab_as, order_by, order, limit Returns a list of posts
getProfilePost 1.3 performance, grab_as Returns any relevant information about the specified profile post
getProfilePosts 1.3 performance, grab_as, order_by, order, limit Returns a list of profile posts
getResource 1.2 performance Returns any relevant information about the specified resource
getResources 1.2 performance Returns a list of the resources
getResourceCategories 1.4 performance Returns a list of resource categories Missing documentation
getStats 1.3 performance Returns a list of relevant stats items
getThread 1.3 performance, grab_as Returns any relevant information about the specified thread
getThreads 1.3 performance, grab_as, order_by, order, limit Returns a list of threads
getUser 1.0 performance, grab_as Returns any relevant information about the specified user
getUsers 1.0 performance, order_by, order, limit Searches through the usernames depending on the input
register 1.3 performance Registers a user for the XenForo software

Error Codes

Error ID Error Message
0 Unknown error
1 Argument: “{ERROR}”, is empty/missing a value
2 “{ERROR}”, is not a supported action
3 Missing argument: “{ERROR}”
4 {ERROR} found with the argument: “{ERROR2}”
5 Authentication error: “{ERROR}”
6 “{ERROR}” is not a valid {ERROR2}
7 Something went wrong when “{ERROR}”: “{ERROR2}”
8 The request had no values set, available fields are: “({ERROR})”
9 You are not permitted to use the “{ERROR}” action on others (remove the value argument)
10 You do not have permission to use the “{ERROR}” action
11 “{ERROR}” is a supported action but there is no code for it yet
12 “{ERROR}” is a unknown request method
13 “{ERROR}” is not an installed addon
14 “{ERROR}” is not an author of any resources
15 Could not find a resource with ID “{ERROR}”
16 Could not find a required model to perform this request: “{ERROR}”
17 The API key has not been changed, make sure you use another API key before using this API.
18 "{ERROR} is a unknown permission name, the request was terminated.
19 Could not find a thread with ID “{ERROR}”.
20 You do not have permissions to view {ERROR}.
21 The “{ERROR}” argument has to be a number.
22 The argument for “order_by”, “{ERROR}”, was not found in the list available order by list: “({ERROR2})”.
22 The argument for “node_type”, “{ERROR}”, was not found in the list available node type list: “({ERROR2})”.

User Error Codes

NOTE: To check for the specific user error id, check for the “user_error_id” of the response.
Example:

{
  "error": 7,
  "message": "Something went wrong when \"registering user\": \"User already exists\"",
  "user_error_id": 40,
  "user_error_field": "username",
  "user_error_key": "usernames_must_be_unique",
  "user_error_phrase": "Usernames must be unique. The specified username is already in use."
}
User Error ID Cause of error
0 Unknown registration error
1 Field was not recognised
2 Group not found
3 User data array was missing
4 The specified user is not registered
5 Invalid custom field array
6 Editing super admins is disabled
7 The add_groups parameter needs to be an array and have at least 1 item
8 The user is already a member of the group(s)
9 No values were changed
10 Missing required a required parameter
11 The remove_groups parameter needs to be an array and have at least 1 item
12 The user is not a member of the group(s)
30 Missing required registration fields
31 Password invalid
32 Name length is too short
33 Name length is too long
34 Name contains disallowed words
35 Name does not follow the required format
36 Name contains censored words
37 Name contains CTRL characters
38 Name contains comma
39 Name resembles an email
40 User already exists
41 Invalid email
42 Email already used
43 Email banned by administrator
44 Invalid timezone
45 Custom title contains censored words
46 Custom title contains disallowed words
47 Invalid date of birth
48 Cannot delete your own account
49 Field contained an invalid value

Additional Parameters

Additional parameters are parameters that can be added to each action.
Note that some actions might not support the parameter, for more information check the additional parameters list for each action.

Summary of additional parameters

Parameter Name Summary
grab_as Allows to grab the action as another user.
performance Adds performance related variables to the response.
order_by Only allowed columns
order Default: descending
limit Default: 10

grab_as

Allows to grab the action as another user.

NOTE: This parameter gets ignored if an API key is not used. Usernames, emails and user ID’s can be used for the grab_as parameter.

Request:

api.php?action=ACTION&hash=API_KEY&grab_as=USERNAME

Example:

api.php?action=getAlerts&hash=____d8e8fca2dc0f896fd7cb4cb0031ba249____&grab_as=Contex

performance

Adds performance related variables to the response.

Request: api.php?performance
Response:

{
  "error": 3,
  "message": "Missing argument: \"hash\"",
  "execution_time": 0.0040709972381592
}

order_by

Orders the results with the “order_by” parameter, check each action for more information about available order_by values.

NOTE: The value of the “order_by” parameter will be added to the response.

Error Codes:

Error ID Cause of error
1 The “order_by” parameter was set but empty
22 The “order_by” parameter was not found in the list of supported order_by parameters

See Error Codes for more information.

Requests:

api.php?action=ACTION&value=VALUE&hash=USERNAME:HASH&order_by=FIELD

api.php?action=ACTION&value=VALUE&hash=API_KEY&order_by=FIELD

Examples:

api.php?action=getUsers&value=Cont*&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08&order_by=message_count

api.php?action=getUsers&value=Cont*&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&order_by=message_count

Response:

[
  {
    "user_id": 1,
    "username": "Contex",
    "message_count": 591
  },
  {
    "user_id": 3,
    "username": "ExampleUser",
    "message_count": 5
  }
]

order

Orders the results with by the “order” parameter.

NOTE: This parameter requires the order_by parameter to be used as well, it will be ignored otherwise.
The value for the “order” parameter will default back to “descending” if an invalid value is requested.

Options for the “order” parameter are:

  • d/desc/descending: Orders the results in a descending order (10 → 0).
  • a/asc/ascending: Orders the results in a ascending order (0 → 10).

Requests:

api.php?action=ACTION&value=VALUE&hash=USERNAME:HASH&order_by=FIELD&order=ORDER

api.php?action=ACTION&value=VALUE&hash=API_KEY&order_by=FIELD&order=ORDER

Examples:

api.php?action=getUsers&value=Cont*&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08&order_by=message_count&order=ASC

api.php?action=getUsers&value=Cont*&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&order_by=message_count&order=ASC

Response:

[
  {
    "user_id": 3,
    "username": "ExampleUser",
    "message_count": 5
  },
  {
    "user_id": 1,
    "username": "Contex",
    "message_count": 591
  }
]

limit

Adds a limit of how many results should be returned.

NOTE: Default value for the limit is by default 100, unless stated otherwise.

Error Codes:

Error ID Cause of error
1 The “limit” parameter was set but empty
21 The “limit” parameter was not a number

See Error Codes for more information.

Requests:

api.php?action=ACTION&value=VALUE&hash=USERNAME:HASH&limit=LIMIT

api.php?action=ACTION&value=VALUE&hash=API_KEY&limit=LIMIT

Examples:

api.php?action=getUsers&value=Cont*&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08&limit=1

api.php?action=getUsers&value=Cont*&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&limit=1

Response:

[
  {
    "user_id": 1,
    "username": "Contex",
    "message_count": 591
  }
]

More information about each action

authenticate

Authenticates the user and returns the hash that the user has to use for future requests.

Error Codes:

Error ID Cause of error
1 The “username” parameter was set but empty
1 The “password” parameter was set but empty
3 The “username” parameter was not set
3 The “password” parameter was not set
4 The “username” parameter is not a registered user
5 Wrong username or password

See Error Codes for more information.

Request: api.php?action=authenticate&username=USERNAME&password=PASSWORD
Example: api.php?action=authenticate&username=Contex&password=MyPassword
Response:

{
  "hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

editUser

Edit the specified user.

NOTE: Make sure this request is sent over a secure connection as you don’t want a MIM attack of the password (password is sent in plain text).
This action also only works with an API key, any attempt on using this action without an API key will result in error id #10 being thrown.
If no values are changed, user error id #3 will be thrown.
The return response will depend on the values changed of the user.

Error Codes:

Error ID Cause of error
1 The “user” parameter was set but empty
1 The “x” parameter was set but empty
3 The “user” parameter was not set
7 The user edit failed, see user error codes for more information
10 API key was not used

See Error Codes for more information.

See User Error Codes for more information regarding user editing related errors.

Required Parameters:

Parameter Value Description Example
user The user. Contex

Additional Parameters:

Parameter Value Description Example
username The username. Contex
password The password. MyPassword
email The email. example@xenapi.net
group The group. Registered
gender The gender. male
custom_title The custom title. The Owner
style_id The style ID. 1
timezone The timezone. Europe\Berlin
visible If user is visible or not. 1
dob_day The date of birth day. 27
dob_month The date of birth month. 12
dob_year The date of birth year. 1980
user_state The user state. valid
custom_fields The custom field(s) and value. custom_field_1=custom_value_1,custom_field_2=custom_value_2
add_groups Add the user to secondary group(s). 5,6,9
remove_groups Remove user from group(s). 5,6
trophy_points Amount of trophy points. 5

See Additional Parameters for more information.

Requests:

api.php?action=editUser&hash=API_KEY&user=API_KEY&FIELD=EDIT_VALUE

Examples:

api.php?action=editUser&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&user=Contex&username=NewUsername

Response:

{"username":"NewUsername"}

getAddon

Returns any relevant addon information about the specified by the “value” parameter.

NOTE: Only addon ID’s can be used for the “value” parameter. Addon ID’s can be found by using the ‘getAddons’ action.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
4 The “value” parameter is not installed

See Error Codes for more information.

Requests:

api.php?action=getAddon&value=ADDON_ID&hash=USERNAME:HASH

api.php?action=getAddon&value=ADDON_ID&hash=API_KEY

Examples:

api.php?action=getAddon&value=PostRating&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAddon&value=PostRating&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "id": "PostRating",
  "title": "Post Ratings",
  "version": "1.5.0",
  "enabled": true,
  "url": "http:\/\/xenforo.com\/community\/resources\/post-ratings-taking-likes-to-the-next-level.410\/"
}

getAddons

Returns all the installed addons, if type is not specified, default (all) is used instead.

Options for the “type” parameter are:

  • all: This is default, and will return all the addons, ignoring if they are installed or not.
  • enabled: Fetches all the addons that are enabled, ignoring the disabled ones.
  • disabled: Fetches all the addons that are disabled, ignoring the enabled ones.

Error Codes:

Error ID Cause of error
1 The “type” parameter was set but empty
3 The “hash” parameter was an API key but the “type” parameter was not set

See Error Codes for more information.

Requests:

api.php?action=getAddons&hash=USERNAME:HASH

api.php?action=getAddons&hash=API_KEY

api.php?action=getAddons&type=TYPE&hash=USERNAME:HASH

api.php?action=getAddons&type=TYPE&hash=API_KEY

Examples:

api.php?action=getAddons&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAddons&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getAddons&type=enabled&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAddons&type=enabled&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "count": 3,
  "addons": [
    {
      "id": "xenCODE_KeywordsMeta",
      "title": "'Keywords' Meta Tag by xenCODE",
      "version": "1.0.0",
      "enabled": true,
      "url": "http:\/\/xenforo.com\/community\/resources\/authors\/mr-goodie2shoes.11736\/"
    },
    {
      "id": "8thos_bar_flex",
      "title": "8thos Bar for Flexile",
      "version": "1.5",
      "enabled": true,
      "url": ""
    },
    {
      "id": "RichUsernameEverywhere",
      "title": "Add Username Style to Last Post",
      "version": "1.0.1",
      "enabled": true,
      "url": "http:\/\/www.madnaoki.com"
    }
  ]
}

getActions

Returns a list of all the available actions and their permission levels.

Request: api.php?action=getActions
Response:

{
  "authenticate": "public",
  "createalert": "api_key",
  "createconversation": "authenticated",
  "createconversationreply": "authenticated",
  "createpost": "authenticated",
  "createprofilepost": "authenticated",
  "createprofilepostcomment": "authenticated",
  "createthread": "authenticated",
  "deletepost": "authenticated",
  "edituser": "api_key",
  "getactions": "public",
  "getaddon": "administrator",
  "getaddons": "administrator",
  "getalerts": "private",
  "getavatar": "public",
  "getconversation": "private",
  "getconversations": "private",
  "getgroup": "public",
  "getnode": "public",
  "getnodes": "public",
  "getpost": "public",
  "getposts": "public",
  "getprofilepost": "authenticated",
  "getprofileposts": "authenticated",
  "getresource": "administrator",
  "getresources": "administrator",
  "getresourcecategories": "administrator",
  "getstats": "public",
  "getthread": "public",
  "getthreads": "public",
  "getuser": "authenticated",
  "getusers": "public",
  "register": "api_key"
}

getAlerts

Grabs the alerts from the specified user, if type is not specified, default (recent alerts) is used instead.

NOTE: The “value” parameter will only work for the user itself and not on others users unless the permission parameter for the “getalerts” action is changed (default permission: private).

Options for the “type” parameter are:

  • fetchPopupItems: Fetch alerts viewed in the last options:alertsPopupExpiryHours hours.
  • fetchRecent: Fetch alerts viewed in the last options:alertExpiryDays days.
  • fetchAll: Fetch alerts regardless of their view_date.

For more information, see /library/XenForo/Model/Alert.php.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
1 The “type” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
3 The “hash” parameter was an API key but the “value” parameter was not set
4 The “value” parameter was not a valid user (not registered)

See Error Codes for more information.

Requests:

api.php?action=getAlerts&hash=USERNAME:HASH

api.php?action=getAlerts&type=fetchAll&hash=USERNAME:HASH

api.php?action=getAlerts&value=USERNAME&hash=USERNAME:HASH

api.php?action=getAlerts&value=USERNAME&type=fetchAll&hash=USERNAME:HASH

api.php?action=getAlerts&value=USERNAME&hash=API_KEY

api.php?action=getAlerts&value=USERNAME&type=fetchAll&hash=API_KEY

Examples:

api.php?action=getAlerts&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAlerts&type=fetchAll&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAlerts&value=JohnDoe&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAlerts&value=JohnDoe&type=fetchAll&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAlerts&value=JohnDoe&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getAlerts&value=JohnDoe&type=fetchAll&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "alerts": {
    "563926": {
      "alert_id": 563926,
      "alerted_user_id": 1,
      "content_type": "user",
      "content_id": 1,
      "action": "following",
      "event_date": 1359927097,
      "view_date": 0,
      "extra_data": "",
      "alert_handler_class": "XenForo_AlertHandler_User",
      "content": {
        "user_id": 1,
        "username": "Contex",
        "email": "contex@xenapi.net",
        "gender": "",
        "custom_title": "",
        "language_id": 1,
        "style_id": 8,
        "timezone": "America\/Los_Angeles",
        "visible": 1,
        "user_group_id": 3,
        "secondary_group_ids": "2,4,7",
        "display_style_group_id": 3,
        "permission_combination_id": 45,
        "message_count": 135,
        "conversations_unread": 0,
        "register_date": 1308798946,
        "last_activity": 1359841741,
        "trophy_points": 28,
        "alerts_unread": 1,
        "avatar_date": 1340917178,
        "avatar_width": 90,
        "avatar_height": 90,
        "gravatar": "",
        "user_state": "valid",
        "is_moderator": 1,
        "is_admin": 1,
        "is_banned": 0,
        "like_count": 47,
        "warning_points": 0,
        "mood_id": 70,
        "friend_count": 0,
        "personal_friend_count": 0
      },
      "user": {
        "user_id": 7252,
        "username": "Jane Doe",
        "gender": "female",
        "gravatar": "",
        "avatar_date": 1359926902
      },
      "new": true,
      "unviewed": true
    }
  },
  "alertHandlers": {
    "XenForo_AlertHandler_User": {
}
}

}

getAvatar

Returns the avatar of user specified by the “value” parameter, if size is not specified or unknown, default (medium) is used instead.

Options for the “size” parameter are:

  • s: Small avatar (48px * 48px)
  • m: Medium avatar (96px * 96px)
  • l: Large avatar (192px * 192px)

NOTE: Only usernames, user ID’s and e-mails can be used for the “value” parameter.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
1 The “size” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
4 The “value” parameter is not a registered user

See Error Codes for more information.

Requests:

api.php?action=getAvatar&hash=USERNAME:HASH

api.php?action=getAvatar&size=SIZE&hash=USERNAME:HASH

api.php?action=getAvatar&value=USERNAME&hash=USERNAME:HASH

api.php?action=getAvatar&value=USERNAME&hash=API_KEY

api.php?action=getAvatar&value=USERNAME&size=SIZE&hash=USERNAME:HASH

api.php?action=getAvatar&value=USERNAME&size=SIZE&hash=API_KEY

Examples:

api.php?action=getAvatar&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15dc15b0f00a08

api.php?action=getAvatar&size=M&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAvatar&value=Contex&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAvatar&value=Contex&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getAvatar&value=Contex&size=M&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAvatar&value=Contex&size=M&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "avatar": "http:\/\/www.xenapi.net\/data\/avatars\/m\/0\/1.jpg?1363566951"
}

getConversations

Grabs the alerts from the specified user, if type is not specified, default (recent alerts) is used instead.

NOTE: The “value” parameter will only work for the user itself and not on others users unless the permission parameter for the “getConversations” action is changed (default permission: private).

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
1 The “type” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
3 The “hash” parameter was an API key but the “value” parameter was not set
4 The “value” parameter was not a valid user (not registered)

See Error Codes for more information.

Requests:

api.php?action=getConversations&hash=USERNAME:HASH

api.php?action=getConversations&value=USERNAME&hash=USERNAME:HASH

api.php?action=getConversations&value=USERNAME&hash=API_KEY

Examples:

api.php?action=getConversations&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getConversations&value=USERNAME&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getConversations&value=USERNAME&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "count": 1,
  "conversations": {
    "4505": {
      "conversation_id": 4505,
      "title": "Conversation Message Title",
      "user_id": 1,
      "username": "Contex",
      "start_date": 1367619271,
      "open_invite": 0,
      "conversation_open": 1,
      "reply_count": 7,
      "recipient_count": 3,
      "first_message_id": 103319,
      "last_message_date": 1367707687,
      "last_message_id": 104208,
      "last_message_user_id": 7917,
      "last_message_username": "Example User",
      "owner_user_id": 1,
      "is_unread": 0,
      "email": "example@xenapi.net",
      "gender": "",
      "custom_title": "",
      "language_id": 1,
      "style_id": 5,
      "timezone": "Europe\/Amsterdam",
      "visible": 1,
      "user_group_id": 3,
      "secondary_group_ids": "2,7",
      "display_style_group_id": 3,
      "permission_combination_id": 63,
      "message_count": 591,
      "conversations_unread": 9,
      "register_date": 1333977020,
      "last_activity": 1368121594,
      "trophy_points": 63,
      "alerts_unread": 0,
      "avatar_date": 1363566951,
      "avatar_width": 192,
      "avatar_height": 192,
      "gravatar": "",
      "user_state": "valid",
      "is_moderator": 1,
      "is_admin": 1,
      "is_banned": 0,
      "like_count": 146,
      "warning_points": 0,
      "recipient_state": "active",
      "last_read_date": 1367707687,
      "message": "First conversation message"
    }
  }
}

getGroup

Returns any relevant group information about the specified by the “value” parameter.

NOTE: Only group titles, user titles and group ID’s can be used for the “value” parameter.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
4 The “value” parameter is not a valid group title/group id

See Error Codes for more information.

Requests:

api.php?action=getGroup&value=GROUP_ID&hash=USERNAME:HASH

api.php?action=getGroup&value=GROUP_ID&hash=API_KEY

api.php?action=getGroup&value=GROUP_TITLE&hash=USERNAME:HASH

api.php?action=getGroup&value=GROUP_TITLE&hash=API_KEY

Examples:

api.php?action=getGroup&value=2&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getGroup&value=2&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getGroup&value=Registered&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getGroup&value=Registered&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "user_group_id": 2,
  "title": "Registered",
  "display_style_priority": 0,
  "username_css": "",
  "user_title": ""
}

getNode

Returns any relevant node information about the specified by the “value” parameter.

NOTE: Only node ID’s can be used for the “value” parameter. Node ID’s can be found by using the ‘getNodes’ action.
Note that the response also depends on what kind of type the node is.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
19 The “value” node could not be found
20 The “value” node was found but the user has no permission to view the node

See Error Codes for more information.

Requests:

api.php?action=getNode&value=NODE_ID&hash=USERNAME:HASH

api.php?action=getNode&value=NODE_ID&hash=API_KEY

Examples:

api.php?action=getNode&value=3&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getNode&value=3&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Responses

Category Response:

{
  "node_id": 3,
  "title": "Main Category",
  "description": "",
  "node_name": null,
  "node_type_id": "Category",
  "parent_node_id": 0,
  "display_order": 1,
  "display_in_list": 1,
  "lft": 1,
  "rgt": 4,
  "depth": 0,
  "style_id": 0,
  "effective_style_id": 0
}

Link Forum Response:

{
  "node_id": 3,
  "title": "Link test",
  "description": "",
  "node_name": null,
  "node_type_id": "LinkForum",
  "parent_node_id": 0,
  "display_order": 1,
  "display_in_list": 1,
  "lft": 13,
  "rgt": 14,
  "depth": 0,
  "style_id": 0,
  "effective_style_id": 0,
  "link_url": "xenapi.net",
  "redirect_count": 0
}

Page Response:

{
  "node_id": 3,
  "title": "Page Title",
  "description": "",
  "node_name": "Page Test",
  "node_type_id": "Page",
  "parent_node_id": 0,
  "display_order": 1,
  "display_in_list": 1,
  "lft": 9,
  "rgt": 10,
  "depth": 0,
  "style_id": 0,
  "effective_style_id": 0,
  "publish_date": 1368717205,
  "modified_date": 1368717205,
  "view_count": 0,
  "log_visits": 0,
  "list_siblings": 0,
  "list_children": 0,
  "callback_class": "",
  "callback_method": ""
}

getNodes

Returns a list of nodes.

NOTE: Permissions come into play if you use user hashes for the request, meaning that nodes will skipped if the user does not have permissions to view the node.
Limit is by default 10, you can change this by using the limit parameter.

Error Codes:

Error ID Cause of error
1 The “node_type” parameter was set but empty
23 The “node_type” parameter was not found in the list of supported node types

See Error Codes for more information.

Additional Parameters:

node_type:

Allows to grab the nodes by type.

Parameter Value Summary
all All the nodes, this is the default option.
category All the categories.
linkforum All the link forums.
forum All the forums.
page All the pages.

See Additional Parameters for more information.

Requests:

api.php?action=getNodes&hash=USERNAME:HASH

api.php?action=getNodes&hash=API_KEY

Examples:

api.php?action=getNodes&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getNodes&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "count": 4,
  "nodes": {
    "1": {
      "node_id": 1,
      "title": "Main Category",
      "description": "",
      "node_name": null,
      "node_type_id": "Category",
      "parent_node_id": 0,
      "display_order": 1,
      "display_in_list": 1,
      "lft": 1,
      "rgt": 4,
      "depth": 0,
      "style_id": 0,
      "effective_style_id": 0
    },
    "2": {
      "node_id": 2,
      "title": "Main Forum",
      "description": "",
      "node_name": null,
      "node_type_id": "Forum",
      "parent_node_id": 1,
      "display_order": 1,
      "display_in_list": 1,
      "lft": 2,
      "rgt": 3,
      "depth": 1,
      "style_id": 0,
      "effective_style_id": 0,
      "discussion_count": 0,
      "message_count": 0,
      "last_post_id": 0,
      "last_post_date": 0,
      "last_post_user_id": 0,
      "last_post_username": "",
      "last_thread_title": "",
      "moderate_messages": 0,
      "allow_posting": 1,
      "count_messages": 1,
      "find_new": 1,
      "prefix_cache": "",
      "default_prefix_id": 0
    },
    "3": {
      "node_id": 3,
      "title": "Test",
      "description": "",
      "node_name": "Test",
      "node_type_id": "Page",
      "parent_node_id": 0,
      "display_order": 1,
      "display_in_list": 1,
      "lft": 9,
      "rgt": 10,
      "depth": 0,
      "style_id": 0,
      "effective_style_id": 0,
      "publish_date": 1368717205,
      "modified_date": 1368717205,
      "view_count": 0,
      "log_visits": 0,
      "list_siblings": 0,
      "list_children": 0,
      "callback_class": "",
      "callback_method": ""
    },
    "4": {
      "node_id": 4,
      "title": "Link test",
      "description": "",
      "node_name": null,
      "node_type_id": "LinkForum",
      "parent_node_id": 0,
      "display_order": 1,
      "display_in_list": 1,
      "lft": 13,
      "rgt": 14,
      "depth": 0,
      "style_id": 0,
      "effective_style_id": 0,
      "link_url": "xenapi.net",
      "redirect_count": 0
    }
  }
}

getPost

Returns any relevant post information about the specified by the “value” parameter.

NOTE: Only post ID’s can be used for the “value” parameter. Post ID’s can be found by using the ‘getPosts’ action.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
19 The “value” post could not be found
20 The “value” post was found but the user has no permission to view the post

See Error Codes for more information.

Requests:

api.php?action=getPost&value=POST_ID&hash=USERNAME:HASH

api.php?action=getPost&value=POST_ID&hash=API_KEY

Examples:

api.php?action=getPost&value=1337&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getPost&value=1337&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "post_id": 1337,
  "thread_id": 1778,
  "user_id": 1,
  "username": "Contex",
  "post_date": 1363518242,
  "message": "Post contents",
  "ip_id": 440223,
  "message_state": "visible",
  "attach_count": 0,
  "position": 8,
  "likes": 4,
  "like_users": "a:4:{i:0;a:2:{s:7:\"user_id\";i:3853;s:8:\"username\";s:9:\"ExampleUser1\";}i:1;a:2:{s:7:\"user_id\";i:3803;s:8:\"username\";s:10:\"ExampleUser2\";}i:2;a:2:{s:7:\"user_id\";i:656;s:8:\"username\";s:12:\"ExampleUser3\";}i:3;a:2:{s:7:\"user_id\";i:5981;s:8:\"username\";s:6:\"ExampleUser4\";}}",
  "warning_id": 0,
  "warning_message": "",
  "node_id": 49,
  "title": "Thread Title",
  "node_title": "Node Title",
  "absolute_url":"http:\/\/xenapi.net\/index.php?posts\/1337\/"
}

getPosts

Returns a list of posts.

NOTE: Permissions come into play if you use user hashes for the request, meaning that posts will skipped if the user does not have permissions to view the thread.
Limit is by default 10, you can change this by using the limit parameter.
Make note that this will also grab the first posts in a thread (position 0).

Error Codes:

Error ID Cause of error
1 The “author” parameter was set but empty
1 The “node_id” parameter was set but empty
1 The “thread_id” parameter was set but empty
4 The “author” parameter is not a registered user
4 Could not find any nodes with the “node_id” parameter
4 Could not find any threads with the “thread_id” parameter
21 The “node_id” parameter was not a number
21 The “thread_id” parameter was not a number

See Error Codes for more information.

Additional Parameters:

order_by:

Allows to order the response by a specific field.

Parameter Value Summary
post_id Post ID.
thread_id Thread ID.
user_id User ID.
username Author username.
attach_count Amount of attachments.
likes Amount of likes.
post_date Post date.
node_id Node ID.

author:

Grabs all the posts made by a specific user.
Valid values are: usernames, user id’s and user emails.

thread_id:

Grabs all the posts by a specific thread ID.
Valid value is only a thread ID.

node_id:

Grabs all the posts by a specific node ID.
Valid value is only a node ID.

See Additional Parameters for more information.

Requests:

api.php?action=getPosts&hash=USERNAME:HASH

api.php?action=getPosts&hash=API_KEY

Examples:

api.php?action=getPosts&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getPosts&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "count": 2,
  "posts": {
    "1": {
      "post_id": 1,
      "thread_id": 1,
      "user_id": 1,
      "username": "Contex",
      "post_date": 1309113432,
      "message": "Post message",
      "ip_id": 336,
      "message_state": "visible",
      "attach_count": 0,
      "position": 0,
      "likes": 0,
      "like_users": "a:0:{}",
      "warning_id": 0,
      "warning_message": "",
      "node_id": 10,
      "title": "Thead title",
      "absolute_url":"http:\/\/xenapi.net\/index.php?posts\/1\/"
    },
    "2": {
      "post_id": 2,
      "thread_id": 2,
      "user_id": 1,
      "username": "Contex",
      "post_date": 1309113527,
      "message": "Post message",
      "ip_id": 337,
      "message_state": "visible",
      "attach_count": 0,
      "position": 0,
      "likes": 0,
      "like_users": "a:0:{}",
      "warning_id": 0,
      "warning_message": "",
      "node_id": 10,
      "title": "Thead title",
      "absolute_url":"http:\/\/xenapi.net\/index.php?posts\/2\/"
    }
  }
}

getProfilePost

Returns any relevant thread information about the specified by the “value” parameter.

NOTE: Only profile post ID’s can be used for the “value” parameter. Profile post ID’s can be found by using the ‘getProfilePosts’ action.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
19 The “value” profile post could not be found
20 The “value” profile post was found but the user has no permission to view the profile post

See Error Codes for more information.

Requests:

api.php?action=getProfilePost&value=POST_ID&hash=USERNAME:HASH

api.php?action=getProfilePost&value=POST_ID&hash=API_KEY

Examples:

api.php?action=getProfilePost&value=1337&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getProfilePost&value=1337&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "profile_post_id": 1337,
  "profile_user_id": 1,
  "user_id": 1,
  "username": "Contex",
  "post_date": 1362256898,
  "message": "Profile post.",
  "ip_id": 413978,
  "message_state": "visible",
  "attach_count": 0,
  "likes": 3,
  "like_users": "a:3:{i:0;a:2:{s:7:\"user_id\";i:1765;s:8:\"username\";s:9:\"ExampleUser1\";}i:1;a:2:{s:7:\"user_id\";i:3259;s:8:\"username\";s:14:\"ExampleUser2\";}i:2;a:2:{s:7:\"user_id\";i:656;s:8:\"username\";s:12:\"ExampleUser3\";}}",
  "comment_count": 4,
  "first_comment_date": 1362270457,
  "last_comment_date": 1362426388,
  "latest_comment_ids": "13539,13551,13573",
  "warning_id": 0,
  "warning_message": ""
}

getProfilePosts

Returns a list of profile posts.

NOTE: Permissions come into play if you use user hashes for the request, meaning that posts will skipped if the user does not have permissions to view the profile post.
Limit is by default 10, you can change this by using the limit parameter.

Error Codes:

Error ID Cause of error
1 The “author” parameter was set but empty
1 The “profile” parameter was set but empty
4 The “author” parameter is not a registered user
4 The “profile” parameter is not a registered user

See Error Codes for more information.

Additional Parameters:

order_by:

Allows to order the response by a specific field.

Parameter Value Summary
profile_post_id Profile post ID.
profile_user_id Profile post user ID.
user_id Profile user ID.
username Profile post username.
post_date Profile post date.
attach_count Amount of attachements.
likes Amount of likes.
comment_count Amount of comments.
first_comment_date First comment date.
last_comment_date Last comment date.

author:

Grabs all the profile posts made by a specific user.
Valid values are: usernames, user id’s and user emails.

profile:

Grabs all the profile posts in a user’s profile.
Valid values are: usernames, user id’s and user emails.

See Additional Parameters for more information.

Requests:

api.php?action=getProfilePosts&hash=USERNAME:HASH

api.php?action=getProfilePosts&hash=API_KEY

Examples:

api.php?action=getProfilePosts&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getProfilePosts&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "count": 2,
  "posts": {
    "1": {
      "post_id": 1,
      "thread_id": 1,
      "user_id": 1,
      "username": "Contex",
      "post_date": 1309113432,
      "message": "Post message",
      "ip_id": 336,
      "message_state": "visible",
      "attach_count": 0,
      "position": 0,
      "likes": 0,
      "like_users": "a:0:{}",
      "warning_id": 0,
      "warning_message": "",
      "node_id": 10,
      "title": "Thead title"
    },
    "2": {
      "post_id": 2,
      "thread_id": 2,
      "user_id": 1,
      "username": "Contex",
      "post_date": 1309113527,
      "message": "Post message",
      "ip_id": 337,
      "message_state": "visible",
      "attach_count": 0,
      "position": 0,
      "likes": 0,
      "like_users": "a:0:{}",
      "warning_id": 0,
      "warning_message": "",
      "node_id": 10,
      "title": "Thead title"
    }
  }
}

getResource

Returns any relevant resource information about the specified by the “value” parameter.

NOTE: Only resource ID’s can be used for the “value” parameter. Resource ID’s can be found by using the ‘getResources’ action.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
4 Resource manager was not found

See Error Codes for more information.

Additional Parameters:

Parameter Value Description Example
grab_description Grab resources with the description of the resource. NONE

Requests:

api.php?action=getResource&value=RESOURCE_ID&hash=USERNAME:HASH

api.php?action=getResource&value=RESOURCE_ID&hash=API_KEY

Examples:

api.php?action=getResource&value=2&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getResource&value=2&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "id": 2,
  "title": "ExampleResource",
  "author_id": 1,
  "author_username": "Contex",
  "state": "visible",
  "creation_date": 1364352654,
  "category_id": 3,
  "version_id": 2,
  "version_string": "1.2.3",
  "file_hash": "6e2702efb9d7b34a48024939f015b5f6",
  "description_id": 2,
  "thread_id": 4601,
  "external_url": "",
  "price": "0.00",
  "currency": "",
  "times_downloaded": 804,
  "times_rated": 1,
  "rating_sum": 5,
  "rating_avg": 5,
  "rating_weighted": 3.1818182468414,
  "times_updated": 0,
  "times_reviewed": 1,
  "last_update": 1364352654
}

getResources

Returns all the resources in the resource manager, if author is not specified, default (all) is used instead.

Error Codes:

Error ID Cause of error
1 The “author” parameter was set but empty
3 The “hash” parameter did not have any resources
4 Resource manager was not found

See Error Codes for more information.

Additional Parameters:

Parameter Value Description Example
grab_description Grab resources with the description of the resource. NONE
category_id Grab resources from a specific category ID. 1

Requests:

api.php?action=getResources&hash=USERNAME:HASH

api.php?action=getResources&hash=API_KEY

api.php?action=getResources&author=AUTHOR&hash=USERNAME:HASH

api.php?action=getResources&author=AUTHOR&hash=API_KEY

api.php?action=getResources&author=AUTHOR&hash=API_KEY&category_id=CATEGORY_ID&grab_description

api.php?action=getResources&author=AUTHOR&hash=API_KEY&grab_description

Examples:

api.php?action=getResources&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getResources&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getResources&author=Contex&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getResources&author=Contex&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getResources&author=Contex&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&category_id=1&grab_description

api.php?action=getResources&author=Contex&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&grab_description

Response:

{
  "total": 2,
  "resources": [
    {
      "id": 2,
      "title": "ExampleResource",
      "author_id": 1,
      "author_username": "Contex",
      "state": "visible",
      "creation_date": 1364352654,
      "category_id": 3,
      "version_id": 2,
      "version_string": "1.2.3",
      "file_hash": "6e2702efb9d7b34a48024939f015b5f6",
      "description_id": 2,
      "thread_id": 4601,
      "external_url": "",
      "price": "0.00",
      "currency": "",
      "times_downloaded": 804,
      "times_rated": 1,
      "rating_sum": 5,
      "rating_avg": 5,
      "rating_weighted": 3.1818182468414,
      "times_updated": 0,
      "times_reviewed": 1,
      "last_update": 1364352654
    },
    {
      "id": 5,
      "title": "ExampleResource2",
      "author_id": 2,
      "author_username": "ExampleUser",
      "state": "visible",
      "creation_date": 1364359662,
      "category_id": 2,
      "version_id": 5,
      "version_string": "1.5.3",
      "file_hash": "6e2702efb9d7b34a48024939f015b5f6",
      "description_id": 5,
      "thread_id": 2449,
      "external_url": "",
      "price": "0.00",
      "currency": "",
      "times_downloaded": 54,
      "times_rated": 4,
      "rating_sum": 20,
      "rating_avg": 5,
      "rating_weighted": 3.5714285373688,
      "times_updated": 0,
      "times_reviewed": 3,
      "last_update": 1364359662
    }
  ]
}

getStats

Returns a list of general stats items.

NOTE: If user hash is used, some data may be ignored unless the user can bypass user privacy.

Additional Parameters:

Parameter Value Description Example
include_deleted Include the deleted threads/posts in the stats. NONE

Requests:

api.php?action=getStats&hash=USERNAME:HASH

api.php?action=getStats&hash=API_KEY

api.php?action=getStats&hash=API_KEY&include_deleted

Examples:

api.php?action=getStats&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getStats&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getStats&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&include_deleted

Response:
{
  "threads": 1822,
  "posts": 350388,
  "conversations": 4541,
  "conversations_messages": 106495,
  "members": 7939,
  "latest_member": {
    "user_id": 7950,
    "username": "Example User"
  },
  "registrations_today": 5,
  "threads_today": 1,
  "posts_today": 549,
  "users_online": 57
}

getThread

Returns any relevant thread information about the specified by the “value” parameter.

NOTE: Only thread ID’s can be used for the “value” parameter. Thread ID’s can be found by using the ‘getThreads’ action.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
19 The “value” thread could not be found
20 The “value” thread was found but the user has no permission to view the thread

See Error Codes for more information.

Requests:

api.php?action=getThread&value=THREAD_ID&hash=USERNAME:HASH

api.php?action=getThread&value=THREAD_ID&hash=API_KEY

Examples:

api.php?action=getThread&value=1337&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getThread&value=1337&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "thread_id": 1337,
  "node_id": 49,
  "title": "Example Title!",
  "reply_count": 30,
  "view_count": 5552,
  "user_id": 1,
  "username": "Contex",
  "post_date": 1364753569,
  "sticky": 1,
  "discussion_state": "visible",
  "discussion_open": 1,
  "discussion_type": "",
  "first_post_id": 311155,
  "first_post_likes": 3,
  "last_post_date": 1367780682,
  "last_post_id": 347382,
  "last_post_user_id": 2,
  "last_post_username": "ContextTest",
  "prefix_id": 0,
  "absolute_url":"http:\/\/xenapi.net\/index.php?thread\/1337\/"
}

getThreads

Returns a list of threads.

NOTE: Permissions come into play if you use user hashes for the request, meaning that threads will skipped if the user does not have permissions to view the thread.
Limit is by default 10, you can change this by using the limit parameter.

Error Codes:

Error ID Cause of error
1 The “author” parameter was set but empty
1 The “node_id” parameter was set but empty
4 The “author” parameter is not a registered user
4 Could not find any nodes with the “node_id” parameter
21 The “node_id” parameter was not a number

See Error Codes for more information.

Additional Parameters:

order_by:

Allows to order the response by a specific field.

Parameter Value Summary
title Thread title.
post_date Post date.
view_count Amount of views.
reply_count Amount of replies.
first_post_likes Amount of likes in the first post.
last_post_date Last post date.
author:

Grabs all the threads made by a specific user.
Valid values are: usernames, user id’s and user emails.

node_id:

Grabs all the threads by a specific node ID.
Valid value is only a node ID.

See Additional Parameters for more information.

Requests:

api.php?action=getThreads&hash=USERNAME:HASH

api.php?action=getThreads&hash=API_KEY

Examples:

api.php?action=getThreads&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getThreads&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "count": 2,
  "threads": {
    "1": {
      "thread_id": 1,
      "node_id": 10,
      "title": "Example Title 1",
      "reply_count": 0,
      "view_count": 916,
      "user_id": 2,
      "username": "Contex",
      "post_date": 1309113432,
      "sticky": 0,
      "discussion_state": "visible",
      "discussion_open": 1,
      "discussion_type": "",
      "first_post_id": 1,
      "first_post_likes": 0,
      "last_post_date": 1309113432,
      "last_post_id": 1,
      "last_post_user_id": 2,
      "last_post_username": "ExampleUser",
      "prefix_id": 0,
      "absolute_url":"http:\/\/xenapi.net\/index.php?thread\/1\/"
    },
    "2": {
      "thread_id": 2,
      "node_id": 10,
      "title": "Example Title 2",
      "reply_count": 0,
      "view_count": 349,
      "user_id": 2,
      "username": "Contex",
      "post_date": 1309113527,
      "sticky": 0,
      "discussion_state": "visible",
      "discussion_open": 1,
      "discussion_type": "",
      "first_post_id": 2,
      "first_post_likes": 0,
      "last_post_date": 1309113527,
      "last_post_id": 2,
      "last_post_user_id": 2,
      "last_post_username": "ExampleUser",
      "prefix_id": 0,
      "absolute_url":"http:\/\/xenapi.net\/index.php?thread\/2\/"
    }
  }
}

getUser

Returns any relevant user information about the specified by the “value” parameter.

NOTE: Only usernames, user ID’s and e-mails can be used for the “value” parameter.
The result varies on the user’s permission level, using an API key bypasses the permission checks.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
4 The “value” parameter is not a registered user

See Error Codes for more information.

Requests:

api.php?action=getUser&hash=USERNAME:HASH

api.php?action=getUser&value=OTHER_USERNAME&hash=USERNAME:HASH

api.php?action=getUser&value=OTHER_USERNAME&hash=API_KEY

api.php?action=getUser&value=EMAIL&hash=USERNAME:HASH

api.php?action=getUser&value=EMAIL&hash=API_KEY

api.php?action=getUser&value=USER_ID&hash=USERNAME:HASH

api.php?action=getUser&value=USER_ID&hash=API_KEY

Examples:

api.php?action=getUser&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUser&value=JohnDoe&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUser&value=JohnDoe&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getUser&value=contex@xenapi.net&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUser&value=contex@xenapi.net&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getUser&value=1&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUser&value=1&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

{
  "user_id": 1,
  "username": "Contex",
  "email": "contex@xenapi.net",
  "gender": "",
  "custom_title": "",
  "language_id": 1,
  "style_id": 5,
  "timezone": "Europe\/Amsterdam",
  "visible": 1,
  "user_group_id": 3,
  "secondary_group_ids": "2,7",
  "display_style_group_id": 3,
  "permission_combination_id": 63,
  "message_count": 591,
  "conversations_unread": 10,
  "register_date": 1333977020,
  "last_activity": 1366660270,
  "trophy_points": 63,
  "alerts_unread": 4,
  "avatar_date": 1363566951,
  "avatar_width": 192,
  "avatar_height": 192,
  "gravatar": "",
  "user_state": "valid",
  "is_moderator": 1,
  "is_admin": 1,
  "is_banned": 0,
  "like_count": 146,
  "warning_points": 0,
  "mood_id": 20,
  "friend_count": 1,
  "personal_friend_count": 0
}

getUsers

Returns any relevant user information about the specified by the “value” parameter.

NOTE: Only usernames can be used for the “value” parameter.
Asterisk (*) can be used as a wildcard.

Error Codes:

Error ID Cause of error
1 The “value” parameter was set but empty
3 Neither of the “value” and “hash” parameters were set
4 The “value” parameter is not a registered user

See Error Codes for more information.

Additional Parameters:

order_by:

Allows to order the response by a specific field.

Parameter Value Summary
user_id The ID of the user.
message_count Amount of posts/messagse.
conversations_unread Amount of unread conversations.
register_date Registration date.
last_activity Last activity date.
trophy_points Amount of trophy points.
alerts_unread Amount of unread alerts.
like_count Amount of likes.

See Additional Parameters for more information.

Requests:

api.php?action=getUsers&value=USERNAME&hash=USERNAME:HASH

api.php?action=getUsers&value=USERNAME&hash=API_KEY

api.php?action=getUsers&value=USERN*&hash=USERNAME:HASH

api.php?action=getUsers&value=USERN*&hash=API_KEY

api.php?action=getUsers&value=U*&hash=USERNAME:HASH

api.php?action=getUsers&value=U*&hash=API_KEY

Examples:

api.php?action=getUsers&value=Contex&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUsers&value=Contex&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getUsers&value=Cont*&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUsers&value=Cont*&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

api.php?action=getUsers&value=C*&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUsers&value=C*&hash=d8e8fca2dc0f896fd7cb4cb0031ba249

Response:

[
  {
    "user_id": 1,
    "username": "Contex"
  },
  {
    "user_id": 2,
    "username": "ExampleUser"
  }
]

register

Registers the user with the XenForo installation.

NOTE: Make sure this request is sent over a secure connection as you don’t want a MIM attack of the password (password is sent in plain text).
This action also only works with an API key, any attempt on using this action without an API key will result in error id #10 being thrown.

Error Codes:

Error ID Cause of error
1 The “username” parameter was set but empty
1 The “password” parameter was set but empty
1 The “email” parameter was set but empty
1 The “x” parameter was set but empty
1 The “language_id” parameter was set but empty
3 The “username” parameter was not set
3 The “password” parameter was not set
3 The “email” parameter was not set
7 The registration failed, see user error codes for more information
10 API key was not used

See Error Codes for more information.

See User Error Codes for more information regarding registration related errors.

Required Parameters:

Parameter Value Description Example
username Username
password Password
email Email

Additional Parameters:

Parameter Value Description Example
group The group. Registered
gender The gender. male
custom_title The custom title. The Owner
style_id The style ID. 1
timezone The timezone. Europe\Berlin
visible If user is visible or not. 1
dob_day The date of birth day. 27
dob_month The date of birth month. 12
dob_year The date of birth year. 1980
user_state The user state. valid
custom_fields The custom field(s) and value. custom_field_1=custom_value_1,custom_field_2=custom_value_2
ip_address The IP of the user. 127.0.0.1
add_groups Add the user to secondary group(s). 5,6,9

group:

Allows to change the group of the user upon registration, make sure that the group exists as it will result in user error id #2 if not.
Please also note that values that are allowed for the “group” parameter are the same as the values for the getGroup action.

user_state:

Allows to change the state of the user upon registration, note that if the “user_state” is not set, the default will be used (depending on your options).
The following options are:

  • email_confirm: Require an email confirmation for the account to become valid.
  • moderated: The account is moderated, and has limited access.
  • valid: The account is valid and does not require any confirmation to be used.

custom_fields:

The custom fields format has to follow this format: custom_fields=custom_field1=custom_value1,custom_field2=custom_value2.
User error id #5 will be thrown if the format is wrong.

add_groups:

Allows to add additiona secondary groups user upon registration, make sure that the group exists as it will result in user error id #2 if not.
Please also note that values that are allowed for the “group” parameter are the same as the values for the getGroup action.
The groups has to be seperated by a comma, like so: 5,6,9

See Additional Parameters for more information.

Requests:

api.php?action=register&hash=API_KEY&username=USERNAME&password=PASSWORD&email=EMAIL

api.php?action=register&hash=API_KEY&username=USERNAME&password=PASSWORD&email=EMAIL&timezone=TIME_ZONE&gender=GENDER&dob_day=DOB_DAY&dob_month=DOB_MONTH&dob_year=DOB_MONTH&ip_address=IP_ADDRESS

api.php?action=register&hash=API_KEY&username=USERNAME&password=PASSWORD&email=EMAIL&timezone=TIME_ZONE&gender=GENDER&dob_day=DOB_DAY&dob_month=DOB_MONTH&dob_year=DOB_MONTH&ip_address=IP_ADDRESS&group*=__GROUP__*&language_id=LANGUAGE_ID&user_state=USER_STATE

Examples:

api.php?action=register&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&username=Contex&password=My_Password&email=me@contex.me

api.php?action=register&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&username=Contex&password=My_Password&email=me@contex.me&timezone=Europe/Berlin&gender=male&dob_day=27&dob_month=12&dob_year=1980&ip_address=172.16.254.1

api.php?action=register&hash=d8e8fca2dc0f896fd7cb4cb0031ba249&username=Contex&password=My_Password&email=me@contex.me&timezone=Europe/Berlin&gender=male&dob_day=27&dob_month=12&dob_year=1980&ip_address=172.16.254.1&group=Registered&language_id=1&user_state=valid

Response:

{
  "visible": 1,
  "user_group_id": 2,
  "user_state": "valid",
  "language_id": 1,
  "username": "Contex",
  "email": "me@contex.me",
  "timezone": "Europe\/Berlin",
  "gender": "male",
  "style_id": 0,
  "secondary_group_ids": "",
  "display_style_group_id": 2,
  "permission_combination_id": 2,
  "message_count": 0,
  "alerts_unread": 0,
  "conversations_unread": 0,
  "register_date": 1368197942,
  "last_activity": 1368197942,
  "trophy_points": 0,
  "avatar_date": 0,
  "avatar_width": 0,
  "avatar_height": 0,
  "gravatar": "",
  "is_moderator": 0,
  "is_admin": 0,
  "is_banned": 0,
  "like_count": 0,
  "custom_title": "",
  "warning_points": 0,
  "user_id": 5,
  "dob_day": 27,
  "dob_month": 12,
  "dob_year": 1980,
  "csrf_token": "f5c36cd98569ae380b4c0383d8310954514ac64b",
  "status": "",
  "status_date": 0,
  "status_profile_post_id": 0,
  "signature": "",
  "homepage": "",
  "location": "",
  "occupation": "",
  "following": "",
  "ignored": "",
  "avatar_crop_x": 0,
  "avatar_crop_y": 0,
  "about": "",
  "facebook_auth_id": 0,
  "custom_fields": "",
  "content_show_signature": 1,
  "show_dob_date": 1,
  "show_dob_year": 1,
  "receive_admin_email": 1,
  "email_on_conversation": 1,
  "default_watch_state": "watch_email",
  "is_discouraged": 0,
  "alert_optout": "",
  "enable_rte": 1,
  "allow_view_profile": "everyone",
  "allow_post_profile": "members",
  "allow_receive_news_feed": "everyone",
  "allow_send_personal_conversation": "members",
  "allow_view_identities": "everyone",
  "scheme_class": "XenForo_Authentication_Core",
  "data": "a:3:{s:4:\"hash\";s:64:\"f1a9f22e79366a9d7b8fcf18178d7bc95c8057ec6f8904b48809f24c2f40efdb\";s:4:\"salt\";s:64:\"f30d7f122f8db2f2c9f92755a667149ed524ae50ab1c0e2f269c4588f8e5835a\";s:8:\"hashFunc\";s:6:\"sha256\";}",
  "remember_key": "11d20c2e9ffbbd7466a872dacf18051a47d94dce"
}

createPost

Creates a new post as the specified user

See Error Codes for more information.

See User Error Codes for more information regarding registration related errors.

Required Parameters::

Parameter Value Description Example
grab_as Post author
thread_id Thread Id
message Message Lorem [b]ipsum[/b]
Add a custom footer
Add a custom sidebar
Clone this wiki locally