REST API Actions

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.

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]

Username	Contex
User Hash	9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
API Key	d8e8fca2dc0f896fd7cb4cb0031ba249

REST API Actions

More information about each action

Clone this wiki locally