> ## Documentation Index > Fetch the complete documentation index at: https://docs.mage.space/llms.txt > Use this file to discover all available pages before exploring further. # List references > GET /v1/references returns the account's saved image and audio references, newest first, with the handle each one is mentioned by. 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}`](/api/endpoints/delete-reference) takes. See [Characters and references](/api/inputs#characters-and-references) for how mentions work. ## OpenAPI ````yaml api/openapi.json GET /v1/references openapi: 3.1.0 info: title: Mage API version: v1 description: >- Run Mage models from your own code: submit a generation, poll its status, download the result. Every request is paid in gems. contact: name: Mage url: https://www.mage.space email: mage@mage.space servers: - url: https://api.mage.space description: Production security: - apiKey: [] tags: - name: Requests description: Submit, poll, and cancel generations. - name: Catalog description: What the API can generate with. - name: Account description: The gems balance. - name: Uploads description: Large input files. - name: Characters description: Saved characters a prompt mentions by `@handle`. - name: References description: Saved image and audio references a prompt mentions by `@handle`. - name: Image models description: One endpoint per image architecture. - name: Video models description: One endpoint per video architecture. paths: /v1/references: get: tags: - References summary: List references description: The account's own image and audio references, newest first. operationId: list_references parameters: - name: limit in: query required: false description: Entities per page, 1 to 200; 50 when omitted. schema: type: integer minimum: 1 maximum: 200 default: 50 - name: cursor in: query required: false description: The `next_cursor` of the previous page. schema: type: string responses: '200': description: One page of references. content: application/json: schema: $ref: '#/components/schemas/ReferenceList' example: 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 '400': $ref: '#/components/responses/InvalidListRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalError' components: schemas: ReferenceList: type: object properties: data: type: array items: type: object properties: id: type: string format: uuid description: >- The reference id, as `DELETE /v1/references/{reference_id}` takes it. handle: type: string description: Mention the reference in a prompt as `@handle`. name: type: string description: The display name. kind: type: string enum: - object - location - pose - outfit - audio description: What the reference is. description: anyOf: - type: string - type: 'null' description: Your notes, or null. image_url: anyOf: - type: string format: uri - type: 'null' description: >- The image, for the four image kinds; null for an audio reference. audio_url: anyOf: - type: string format: uri - type: 'null' description: 'The processed clip, for `kind: "audio"`; null otherwise.' created_at: type: string format: date-time description: When it was created. required: - id - handle - name - kind - description - image_url - audio_url - created_at additionalProperties: false description: The page, newest first. next_cursor: anyOf: - type: string - type: 'null' description: Send as `cursor` for the next page; null on the last page. required: - data - next_cursor additionalProperties: false Error: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - invalid_request - invalid_config - architecture_not_found - architecture_retired - request_not_found - character_not_found - reference_not_found - not_found - insufficient_gems - forbidden - content_blocked - request_finished - handle_taken - too_many_requests - generation_failed - internal_error description: A stable error code; treat an unknown code by its HTTP status. message: type: string description: What went wrong, for a person. request_id: description: >- The request the refusal belongs to, when one was recorded before the refusal. type: string format: uuid gems_required: description: The price of the refused generation, on `insufficient_gems`. type: number docs_url: description: Where to read the API reference, on `not_found`. type: string format: uri handle: description: The handle that is taken, on `handle_taken`. type: string required: - code - message additionalProperties: true description: Further fields depend on the code. required: - error additionalProperties: false responses: InvalidListRequest: description: >- `limit` is not a whole number in range, or `cursor` is not a `next_cursor` from an earlier page. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: '`limit` must be a whole number from 1 to 200.' Unauthorized: description: The key is missing, malformed, unknown, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: The API key is invalid or has been revoked. InternalError: description: >- Something failed on Mage's side. Retry, and contact support if it persists. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_error message: >- Something went wrong on our side. Retry, and contact support if it persists. securitySchemes: apiKey: type: http scheme: bearer description: >- An API key from Settings → API, sent as `Authorization: Bearer mage_sk_…`. Keys are for server-side code only. ````