Develop
Develop
Select your platform

Challenges Server to Server APIs

Notice of feature support change
Due to the scheduled deprecation of the Scoreboard app on December 20th, 2024, the Challenges API is currently unsupported. We currently do not recommend implementing the Challenges API into your app, pending future updates.
Server to Server APIs
The server-to-server (S2S) Rest APIs provide a secure channel to interact with Meta Horizon platform services. For example, you might want to update a Meta Quest Challenge’s visibility from private to public. This topic provides details about the Meta Quest Challenge server calls that you can make.

Message Basics

There are some server to server message basics you should be familiar with.

Server-to-Server API requirements

Calls to these APIs must meet the following requirements:

Endpoint

Make all server-to-server requests to this endpoint:
https://graph.oculus.com

Access token

Include an access token with every request to authenticate it either as a valid server request or on behalf of a specific user. The access token can be one of the following:

App credentials

App credentials authenticate your server’s back-end as a trusted resource. Never share these credentials with any client-side application.
The access token with app credentials includes the App ID and App Secret from the API page on the Meta Horizon Developer Dashboard. It follows this format: OC|$APPID|$APPSECRET.
If your credentials are compromised or you need new API credentials, generate a new app secret. Changing the app secret will revoke the permissions of the previous one. Accessing the app secret requires an administrator account.

User access token

A user access token authenticates requests on behalf of a user. Use this token type when actions relate to a specific user. An example case is updating a client-authoritative leaderboard with the results of a server-hosted multiplayer match. For each user, you would use the user access token to authenticate your server as you make requests to update their leaderboards.
Retrieve the user token with the Users.getAccessToken() method.
A user access token contains FRL or OC and a long alpha numeric string similar to the following: FRL12342GhFccWvUBxPMR4KXzM5s2ZCMp0mlWGq0ZBrOMXyjh4EmuAPvaXiMCAMV9okNm9DXdUA2EWNplrQ.
Additionally, you can retrieve your user token for testing purposes at the ‘User Token’ section of the API page of the Meta Horizon Developer Dashboard, which is at the left navigation bar.

App ID

Some server calls require an app ID, which you can find on the API page of the Meta Horizon Developer Dashboard.

Create a Challenge

URL: https://graph.oculus.com/{app_id}/challenges
Method: POST
Example Request:
POST /1234757621998335/challenges/?api_name=leaderboard_api_name=hello_friends&creation_type=DEVELOPER_CREATED&visibility=PRIVATE&title=sample_challenge
Host: graph.oculus.com
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5
Example cURL Request:
curl -X POST https://graph.oculus.com/$APP_ID/challenges -d "access_token=OC|$APP_ID|$APP_SECRET" -d "leaderboard_api_name=sample_leaderboard" -d "creation_type=DEVELOPER_CREATED" -d "visibility=PRIVATE" -d "title=sample_challenge"
Parameter
Param type
Description
Type
leaderboard_api_name
Query
Required. The unique API name for the leaderboard associated with your challenge.
string
creation_type
Query
Required. Should always be “DEVELOPER_CREATED” using this method.
Enum, value DEVELOPER_CREATED
visibility
Query
Required. Either PUBLIC, INVITE_ONLY, or PRIVATE.
  • PUBLIC: Any user can see the challenge, and can join even without an invite.
  • INVITE_ONLY: Any user can see the challenge, but only those with an invite can join it. This is intended to be used for e.g. challenges with special limited participants, but when you still want to publicize the challenge so others can observe.
  • PRIVATE: Only those with an invite can see the challenge or join it.
Enum, value PUBLIC, INVITE_ONLY, or PRIVATE
title
Query
The title of the challenge.
string
description
Query
A description of the challenge.
string
start_date
Query
Start date of the challenge.
date
end_date
Query
End date of the challenge. Defaults to three days later.
date
fields
Query
A comma separated list of fields to retrieve. Possible values -
  • id
  • title
  • description
  • start_date
  • end_date
  • leaderboard
  • creation_type
  • visibility
  • entries
  • invited_users
  • participants
A comma-separated list of strings
Example response:
{
	"id": "2643098232993236",
	"title": "hello_challenge",
	"start_date": "2020-07-14T22:58:24+0000",
	"end_date": "2020-07-17T22:58:24+0000",
	"leaderboard": {
		"id": "3123283331082599"
	}
}

Change a challenge’s visibility, start or end date

URL: https://graph.oculus.com/{challenge_id}
Method: POST
Example Request:
POST /1234757621998335?visibility=INVITE_ONLY
Host: graph.oculus.com
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5
Example cURL Request:
curl -X POST https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET" -d "visibility=INVITE_ONLY"
Parameter
Param type
Description
Type
visibility
Query
Either PUBLIC, INVITE_ONLY, or PRIVATE.
  • PUBLIC: Any user can see the challenge, and can join even without an invite.
  • INVITE_ONLY: Any user can see the challenge, but only those with an invite can join it. This is intended to be used for e.g. challenges with special limited participants, but when you still want to publicize the challenge so others can observe.
  • PRIVATE: Only those with an invite can see the challenge or join it. This is generally only for user-created challenges among friends, not developer-created challenges.
Enum, value “PUBLIC”, “INVITE_ONLY”, or “PRIVATE"
start_date
Query
Date
integer that represents a Unix timestamp
end_date
Query
Date. This defaults to 3 hours after the start date.
integer that represents a Unix timestamp
fields
Query
A comma separated list of fields to retrieve. Possible values -
  • id
  • title
  • description
  • start_date
  • end_date
  • leaderboard
  • creation_type
  • visibility
  • entries
  • invited_users
  • participants
A comma-separated list of strings
Example return:
{
	"success": true
}

Delete a challenge

URL:https://graph.oculus.com/{challenge_id}
Method: DELETE
DELETE /12347576219983357
Authorization: Bearer OC|1234f7a788b0c0b270f9691d0a06d5a5
Example cURL Request:
curl -X DELETE https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET"
Example return:
{
	"success": true
}

Get a list of challenges in your application

Use this method to return a list of challenges in your application attached to a given leaderboard.
URL: https://graph.oculus.com/{app_id}/challenges
Method: GET
Example Request:
GET /1234757621998335/challenges
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
Example cURL Request:
curl -G https://graph.oculus.com/$APP_ID/challenges -d "access_token=OC|$APP_ID|$APP_SECRET"
Parameter
Param type
Description
Type
leaderboard_api_name
Query
By default will get challenges for all leaderboards. Use leaderboard_api_name to return challenges for a single leaderboard.
String
include_active_challenges
Query
Default true. If false, does not return past challenges for your application.
Boolean
include_past_challenges
Query
Default false. If true, returns challenges with end dates in the past.
Boolean
include_future_challenges
Query
Default false If true, returns challenges with start dates in the future.
Boolean
fields
Query
A comma separated list of fields to retrieve. Possible values -
  • id
  • title
  • description
  • start_date
  • end_date
  • leaderboard
  • creation_type
  • visibility
  • entries
  • invited_users
  • participants
A comma-separated list of strings

Retrieve Data about a Challenge

Use this method to return information about one challenge in your application.
URL: https://graph.oculus.com/{challenge_id}
Method: GET
Example Request:
GET /1234757621998335?fields=id,title,description,start_date,end_date,leaderboard
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
Example cURL Request:
curl -G https://graph.oculus.com/$CHALLENGE_ID -d "access_token=OC|$APP_ID|$APP_SECRET" -d "fields=id,title,description,start_date,end_date,leaderboard"
Parameter
Param type
Description
Type
fields
Query
A comma separated list of fields to retrieve. Possible values -
  • id
  • title
  • description
  • start_date
  • end_date
  • leaderboard
  • creation_type
  • visibility
  • entries
  • invited_users
  • participants
A comma-separated list of strings
Example response:
{
	"title": "sample_challenge",
	"description": "Let's see who can climb the highest!",
	"id" : "2643098232993236",
  "leaderboard": {
        "id": "7410520479067243"
    }
}

Get Challenge Score Entries

Use this method to return score entries for one challenge.
Method: GET
URL: https://graph.oculus.com/{challenge_id}/entries
Example Request:
GET /1234757621998335/entries
Host: graph.oculus.com
Authorization: Bearer OC|1234757621998335|1234f7a788b0c0b270f9691d0a06d5a5
Example cURL Request:
curl -G https://graph.oculus.com/$CHALLENGE_ID/entries -d "access_token=OC|$APP_ID|$APP_SECRET"
Parameter
Param type
Description
Type
filter
Query
This reduces the scope of score entries that are returned.
Enum, value NONE(default), FRIENDS, or USER_IDS
  • NONE: No filter enabled on the leaderboard.
  • FRIENDS: Filter the leaderboard to include only friends of the current user.
  • USER_IDS: Filter the leaderboard to include specific user IDs. Use this filter to get rankings for users that are competing against each other
start_at
Query
Defines which order the entries are returned in.
Enum, value TOP (default), VIEWER, VIEWER_OR_TOP, or OFFSET
offset
Query
Required when the start-at value is offset and indicates the offset value to use.
Integer
limit
Query
Reduce the amount of entries returned to this number.
Integer
user_ids
Query
Return entries for a given set of users.
List of integers representing user ids.
fields
Query
A comma separated list of fields to retrieve. Possible values -
  • id
  • challenge
  • user
  • rank
  • score
  • timestamp
  • extra_data
A comma separated list of strings
Did you find this page helpful?
Thumbs up icon
Thumbs down icon
Nav Logo
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
Virtual reality / Meta Horizon
English (US)
© 2025 Meta