Skip to content

REST API Actions

Jump to bottom Edit New page
Contex edited this page Apr 29, 2013 · 33 revisions

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

For these examples I’m using
Contex as the username,
9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 as the user hash and
d8e8fca2dc0f896fd7cb4cb0031ba249 as the API key.

Summary of actions

Action Name Version Added Summary
authenticate 1.0 Authenticates the user and returns the hash that the user has to use for future requests
getAddon 1.2 Returns any relevant information about the specified addon
getAddons 1.2 Returns a list of the installed addons
getActions 1.0 Returns a list of all the available actions and their permission levels
getAlerts 1.1 Returns the alerts of the specified user
getAvatar 1.0 Returns the avatar of the specified user
getGroup 1.0 Returns any relevant information about the specified group
getResource 1.2 Returns any relevant information about the specified resource
getResources 1.2 Returns a list of the resources
getUser 1.0 Returns any relevant information about the specified user
getUsers 1.0 Searches through the usernames depending on the input

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 No user found with the argument: “{ERROR}”
5 Authentication error: “{ERROR}”
6 “{ERROR}” is not a valid hash
7 No group found with the argument: “{ERROR}”
8 You do not have permissions to use the “{ERROR}” action
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.

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” argument was set but empty
1 The “password” argument was set but empty
3 The “username” argument was not set
3 The “password” argument was not set
4 The “username” argument 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"
}

getAddon

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

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” argument was set but empty
3 Neither of the “value” and “hash” arguments were set
4 The “value” argument 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” argument 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” argument was set but empty
3 The “hash” argument was an API key but the “type” argument 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:

{
  "getactions": "public",
  "getalerts": "private",
  "getuser": "authenticated",
  "getavatar": "public",
  "getusers": "public",
  "getgroup": "public",
  "authenticate": "public"
  "getaddons": "administrator"
  "getaddon": "administrator"
  "getresources": "administrator"
  "getresource": "administrator"
}

getAlerts

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

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

Options for the “type” argument 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” argument was set but empty
1 The “type” argument was set but empty
3 Neither of the “value” and “hash” arguments were set
3 The “hash” argument was an API key but the “value” argument was not set
4 The “value” argument 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": "[email protected]",
        "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” argument, if size is not specified or unknown, default (medium) is used instead.

Options for the “size” argument 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” argument was set but empty
1 The “size” argument was set but empty
3 Neither of the “value” and “hash” arguments were set
4 The “value” argument 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:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

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"
}

getResource

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

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” argument was set but empty
3 Neither of the “value” and “hash” arguments were set
4 Resource manager was not found

See Error Codes for more information.

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=getAlerts&value=2&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getAlerts&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,
  "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” argument was set but empty
3 The “hash” argument did not have any resources
4 Resource manager was not found

See Error Codes for more information.

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

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

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,
      "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,
      "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
    }
  ]
}

getUser

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

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” argument was set but empty
3 Neither of the “value” and “hash” arguments were set
4 The “value” argument 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=[email protected]&hash=Contex:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

api.php?action=getUser&value=[email protected]&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": "[email protected]",
  "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
}</pre



getUsers


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


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” argument was set but empty
3 Neither of the “value” and “hash” arguments were set
4 The “value” argument is not a registered user

See Error Codes 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:

{[
  {
    "username": "Contex"
  },
  {
    "username": "ContexTest"
  }
]
Add a custom footer
Add a custom sidebar
Clone this wiki locally