List references
curl --request GET \
--url https://api.mage.space/v1/references \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.mage.space/v1/references"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.mage.space/v1/references', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"id": "a81f0c5d-2e6b-4f93-b7c4-0d9e5a3c2f18",
"handle": "red-coat",
"name": "Red coat",
"kind": "outfit",
"description": null,
"image_url": "https://cdn3.mage.space/references/user/image/4c2d.jpg",
"audio_url": null,
"created_at": "2026-09-18T10:05:00.000Z"
}
],
"next_cursor": null
}{
"error": {
"code": "invalid_request",
"message": "`limit` must be a whole number from 1 to 200."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry, and contact support if it persists."
}
}Endpoints
List references
GET /v1/references returns the account’s saved image and audio references, newest first, with the handle each one is mentioned by.
GET
/
v1
/
references
List references
curl --request GET \
--url https://api.mage.space/v1/references \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.mage.space/v1/references"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.mage.space/v1/references', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"data": [
{
"id": "a81f0c5d-2e6b-4f93-b7c4-0d9e5a3c2f18",
"handle": "red-coat",
"name": "Red coat",
"kind": "outfit",
"description": null,
"image_url": "https://cdn3.mage.space/references/user/image/4c2d.jpg",
"audio_url": null,
"created_at": "2026-09-18T10:05:00.000Z"
}
],
"next_cursor": null
}{
"error": {
"code": "invalid_request",
"message": "`limit` must be a whole number from 1 to 200."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry, and contact support if it persists."
}
}Your own references, newest first, with
limit and cursor for paging: send the next_cursor of one page as cursor to get the next, until it is null. Each entry’s kind says what it is (object, location, pose, outfit, or audio); the four image kinds carry image_url, an audio reference carries audio_url. handle is what a prompt mentions as @handle; id is what DELETE /v1/references/{reference_id} takes.
See Characters and references for how mentions work.Authorizations
An API key from Settings → API, sent as Authorization: Bearer mage_sk_…. Keys are for server-side code only.
Query Parameters
Entities per page, 1 to 200; 50 when omitted.
Required range:
1 <= x <= 200The next_cursor of the previous page.
Last modified on September 18, 2026

