Synchronize items in a specific list with a provided set of items. This endpoint performs a comprehensive synchronization that:

• Creates new items that don’t exist in the list
• Updates existing items with new data
• Archives items that exist in the database but are not included in the request

This is ideal for keeping a list in sync with an external data source.

Authentication

Authenticate using an API key passed via the X-API-Key header. The user query parameter is required and must match the API key owner username.

Request

Method: POST

URL: https://unduel.com/api/v1/list/synchronize-items?user=<username>

Headers:

Query Parameters:

Take the list id from the URL on the Make a List page for your list. Your topic id can be taken from the URL on your lists page. It will look something like “oliver-user”.

Request Body

interface SynchronizeItemsRequestBody {
    listId: string;
    topicId: string;
    items: EditableItem[];
}

Item Schema

interface EditableItem {
    /**
     * Item ID (optional, overwritten on new items).
     * Recommended for making edits to existing items.
     * If omitted, items can be matched by nameRef instead,
     * as long as there are no duplicate nameRefs on the list.
     */
    id?: string;

    /** Item name (required, non-empty string) */
    name: string;

    /**
     * URL-safe slug (required).
     * Used as a fallback identifier when id is not provided.
     * Can be overwritten when id is provided.
     */
    nameRef: string;

    /** Subtitle (required, string or null) */
    subtitle: string | null;

    /** Image URL (required, must be a valid URL or null) */
    imageUrl: string | null;

    /**
     * Image width in pixels (required, positive integer or null).
     * Must be a positive integer when imageUrl is provided.
     */
    imageWidth: number | null;

    /**
     * Image height in pixels (required, positive integer or null).
     * Must be a positive integer when imageUrl is provided.
     */
    imageHeight: number | null;

    /** Is the image pixel art? (required, boolean or null) */
    pixelated: boolean | null;

    /** Item description (required, string or null) */
    description: string | null;

    /** Array of tag name strings for filtering (required) */
    tags: string[];

    /** Custom properties as key-value pairs (required, must be an object) */
    properties: { [key: string]: string };

    /** Source URL for the item (required, must be a valid URL or null) */
    source: string | null;

    /**
     * External links for the item (required).
     * Provide an empty array if no external links are needed.
     */
    externalLinks: ExternalLinkMinimal[];
}

interface ExternalLinkMinimal {
    /** The external link URL (required, non-empty string) */
    url: string;

    /** A label to override the type label */
    label: string | null;

    /** Specifies the type of link, if applicable */
    externalLinkTypeName:
        | "WIKI"
        | "STORE"
        | "TUNEBAT"
        | "SPOTIFY"
        | "YOUTUBE"
        | null;
}

Example