> ## Documentation Index > Fetch the complete documentation index at: https://docs.magichour.ai/llms.txt > Use this file to discover all available pages before exploring further. # List saved items > Returns active saved items owned by the authenticated account, newest first. Each item includes every saved asset with a durable file_path for reuse in compatible generation APIs and a temporary signed URL for previewing or downloading. Filter by type to find characters, references, voices, moodboards, or brand kits. To fetch the next page, pass the response's next_cursor as cursor. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/saved-items openapi: 3.0.2 info: title: Magic Hour API version: beta description: > Magic Hour provides a REST API (beta) for generating and editing video, images, and audio using AI. Webhook documentation can be found [here](https://docs.magichour.ai/webhook-reference). If you have any questions, please reach out to us via [discord](https://discord.gg/JX5rgsZaJp). # Authentication Every request requires an API key. To get started, first generate your API key [here](https://magichour.ai/developer?tab=api-keys&utm_source=docs&utm_medium=referral&utm_campaign=api-reference). Then, add the `Authorization` header to the request. | Key | Value | |-|-| | Authorization | Bearer mhk_live_apikey | > **Warning**: API generation and editing requests consume account credits. Cost varies by tool, model, and settings; see [API pricing](https://magichour.ai/api#api-cost-calculator). termsOfService: https://magichour.ai/terms-of-service servers: - url: https://api.magichour.ai security: [] tags: - name: Video Projects description: API related to video projects - name: Image Projects description: API related to image projects - name: Audio Projects description: API related to audio projects - name: Files description: API related to uploading and reusing assets - name: Account description: API related to the account that owns the API key paths: /v1/saved-items: get: tags: - Files summary: List saved items description: >- Returns active saved items owned by the authenticated account, newest first. Each item includes every saved asset with a durable file_path for reuse in compatible generation APIs and a temporary signed URL for previewing or downloading. Filter by type to find characters, references, voices, moodboards, or brand kits. To fetch the next page, pass the response's next_cursor as cursor. operationId: savedItems.list parameters: - name: type in: query description: Only return saved items of this type. schema: type: string enum: - character - reference - voice - moodboard - brand_kit example: character - name: limit in: query description: Maximum number of saved items to return. Defaults to 20. schema: default: 20 type: integer minimum: 1 maximum: 100 example: 20 - name: cursor in: query description: Opaque pagination cursor from the previous response's next_cursor. schema: type: string minLength: 1 responses: '200': description: '200' content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string description: Unique ID of the saved item. example: cuid-example type: type: string enum: - character - reference - voice - moodboard - brand_kit description: Saved item type. example: character name: type: string nullable: true description: User-provided name of the saved item. example: Alex assets: type: array items: type: object properties: file_path: type: string description: >- Durable asset path. Pass it to a compatible API asset field without uploading it again. example: saved-items/user-id/item-id/image.png media_kind: type: string enum: - IMAGE - VIDEO - AUDIO description: Media type of the asset. example: IMAGE is_primary: type: boolean description: >- Whether this asset is the saved item's primary asset. example: true url: type: string format: uri description: >- Signed URL for previewing or downloading the asset. Expires after 24 hours. url_expires_at: type: string format: date-time description: >- When the signed URL expires. The saved asset and file_path do not expire. example: '2026-09-17T00:00:00.000Z' required: - file_path - media_kind - is_primary - url - url_expires_at required: - id - type - name - assets next_cursor: type: string nullable: true description: >- Cursor for the next page, or null when there are no more saved items. required: - items - next_cursor '400': description: Invalid Request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - invalid_request description: >- Machine-readable error code. - `invalid_request`: Fix request syntax or validation errors before retrying. message: type: string description: Human-readable error message. '401': description: Unauthorized content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - unauthorized description: |- Machine-readable error code. - `unauthorized`: Provide a valid API key before retrying. message: type: string description: Human-readable error message. '500': description: Internal Server Error content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - internal_server_error description: >- Machine-readable error code. - `internal_server_error`: Retry later or contact support if the error continues. message: type: string description: Human-readable error message. security: - bearerAuth: [] x-codeSamples: - lang: python source: |- from magic_hour import Client from os import getenv client = Client(token=getenv("MAGIC_HOUR_API_KEY")) res = client.v1.saved_items.list(limit=20, type_="character") - lang: javascript source: >- import { Client } from "magic-hour"; const client = new Client({ token: process.env["MAGIC_HOUR_API_KEY"] }); const res = await client.v1.savedItems.list(); - lang: go source: "package main\n\nimport (\n\tos \"os\"\n\n\tsdk \"github.com/magichourhq/magic-hour-go/client\"\n\tnullable \"github.com/magichourhq/magic-hour-go/nullable\"\n\tsaved_items \"github.com/magichourhq/magic-hour-go/resources/v1/saved_items\"\n\ttypes \"github.com/magichourhq/magic-hour-go/types\"\n)\n\nfunc main() {\n\tclient := sdk.NewClient(\n\t\tsdk.WithBearerAuth(os.Getenv(\"MAGIC_HOUR_API_KEY\")),\n\t)\n\tres, err := client.V1.SavedItems.List(saved_items.ListRequest{\n\t\tLimit: nullable.NewValue(20),\n\t\tType: nullable.NewValue(types.V1SavedItemsListTypeEnumCharacter),\n\t})\n}" - lang: rust source: |- let client = magic_hour::Client::default() .with_bearer_auth(&std::env::var("MAGIC_HOUR_API_KEY").unwrap()); let res = client .v1() .saved_items() .list(magic_hour::resources::v1::saved_items::ListRequest { limit: Some(20), type_: Some(magic_hour::models::V1SavedItemsListTypeEnum::Character), ..Default::default() }) .await; - lang: curl source: |- curl --request GET \ --url https://api.magichour.ai/v1/saved-items \ --header 'accept: application/json' \ --header "authorization: Bearer $MAGIC_HOUR_API_KEY" - lang: php source: |- "https://api.magichour.ai/v1/saved-items", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "GET", CURLOPT_HTTPHEADER => [ "accept: application/json", "authorization: Bearer " ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } - lang: java source: >- HttpResponse response = Unirest.get("https://api.magichour.ai/v1/saved-items") .header("accept", "application/json") .header("authorization", "Bearer ") .asString(); components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer authentication header of the form `Bearer `, where `` is your API key. To get your API key, go to [Developer Hub](https://magichour.ai/developer?tab=api-keys&utm_source=docs&utm_medium=referral&utm_campaign=api-reference) and click "Create new API Key". ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.