# Memories API

Source: https://frameleaf.app/docs/api/reference/memories/

Use your own server and its scoped API keys.

## Retrieve memories

GET /api/memories

Retrieve a list of memories. Memories are sorted descending by creation date by default, although they can also be sorted in ascending order, or randomly.

```json
{
  "description": "Retrieve a list of memories. Memories are sorted descending by creation date by default, although they can also be sorted in ascending order, or randomly.",
  "operationId": "searchMemories",
  "parameters": [
    {
      "name": "for",
      "required": false,
      "in": "query",
      "description": "Filter by date",
      "schema": {
        "format": "date",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
        "example": "2024-01-01",
        "type": "string"
      }
    },
    {
      "name": "id",
      "required": false,
      "in": "query",
      "description": "Memory ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "isHidden",
      "required": false,
      "in": "query",
      "description": "Only the memories the owner hid (true); hidden memories are left out otherwise",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isSaved",
      "required": false,
      "in": "query",
      "description": "Filter by saved status",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isTrashed",
      "required": false,
      "in": "query",
      "description": "Include trashed memories",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isUpcoming",
      "required": false,
      "in": "query",
      "description": "Filter by memories that have not been shown yet",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "order",
      "required": false,
      "in": "query",
      "schema": {
        "$ref": "#/components/schemas/MemorySearchOrder"
      }
    },
    {
      "name": "page",
      "required": false,
      "in": "query",
      "description": "Page number",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "type": "integer"
      }
    },
    {
      "name": "size",
      "required": false,
      "in": "query",
      "description": "Number of memories to return",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "type": "integer"
      }
    },
    {
      "name": "type",
      "required": false,
      "in": "query",
      "schema": {
        "$ref": "#/components/schemas/MemoryType"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/MemoryResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve memories",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.read"
}
```

## Create a memory

POST /api/memories

Create a new memory by providing a name, description, and a list of asset IDs to include in the memory.

```json
{
  "description": "Create a new memory by providing a name, description, and a list of asset IDs to include in the memory.",
  "operationId": "createMemory",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Create a memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.create"
}
```

## Retrieve memory exports

GET /api/memories/exports

Retrieve the caller's own private highlight exports, newest first, optionally limited to a single memory. This is the durable job state the Activity page reads.

```json
{
  "description": "Retrieve the caller's own private highlight exports, newest first, optionally limited to a single memory. This is the durable job state the Activity page reads.",
  "operationId": "getMemoryExports",
  "parameters": [
    {
      "name": "memoryId",
      "required": false,
      "in": "query",
      "description": "Only return exports of this memory",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/MemoryExportResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve memory exports",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.read"
}
```

## Delete a memory export

DELETE /api/memories/exports/{id}

Cancel the export if it is still running, then delete the run and its archive.

```json
{
  "description": "Cancel the export if it is still running, then delete the run and its archive.",
  "operationId": "deleteMemoryExport",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete a memory export",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.delete"
}
```

## Retrieve a memory export

GET /api/memories/exports/{id}

Retrieve the current state of one of the caller's own private highlight exports.

```json
{
  "description": "Retrieve the current state of one of the caller's own private highlight exports.",
  "operationId": "getMemoryExport",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryExportResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve a memory export",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.read"
}
```

## Cancel a memory export

POST /api/memories/exports/{id}/cancel

Ask for a running export to stop. A queued export is cancelled immediately; a running one stops at its next asset. Cancelling a finished export returns its final state unchanged.

```json
{
  "description": "Ask for a running export to stop. A queued export is cancelled immediately; a running one stops at its next asset. Cancelling a finished export returns its final state unchanged.",
  "operationId": "cancelMemoryExport",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryExportResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Cancel a memory export",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.update"
}
```

## Download a memory export

GET /api/memories/exports/{id}/download

Download the finished archive for one of the caller's own exports. The archive is not reachable by any other route and is deleted when it expires.

```json
{
  "description": "Download the finished archive for one of the caller's own exports. The archive is not reachable by any other route and is deleted when it expires.",
  "operationId": "downloadMemoryExport",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/octet-stream": {
          "schema": {
            "format": "binary",
            "type": "string"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Download a memory export",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.read"
}
```

## Save a memory highlight to the library

POST /api/memories/exports/{id}/library

Save a finished highlight video of one of the caller's own memories to their library. Until then it is kept with the memory, out of the library, and removed with it.

```json
{
  "description": "Save a finished highlight video of one of the caller's own memories to their library. Until then it is kept with the memory, out of the library, and removed with it.",
  "operationId": "saveMemoryExportToLibrary",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryExportResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Save a memory highlight to the library",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.update"
}
```

## Remove a memories show-less rule

DELETE /api/memories/show-less

Remove one of the caller's show-less rules, so its memories are generated and shown again, and return every rule.

```json
{
  "description": "Remove one of the caller's show-less rules, so its memories are generated and shown again, and return every rule.",
  "operationId": "removeMemoryShowLess",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryShowLessDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/MemoryShowLessResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Remove a memories show-less rule",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.update"
}
```

## Retrieve memories show-less rules

GET /api/memories/show-less

Retrieve the caller's own rules: people, pets, dates and kinds of memory they asked to see less of. Memories of them are neither generated nor shown.

```json
{
  "description": "Retrieve the caller's own rules: people, pets, dates and kinds of memory they asked to see less of. Memories of them are neither generated nor shown.",
  "operationId": "getMemoryShowLess",
  "parameters": [],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/MemoryShowLessResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve memories show-less rules",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.read"
}
```

## Show less of a person, pet, date or kind of memory

POST /api/memories/show-less

Add a show-less rule for one of the caller's own people or pets, a date written as 'MM-dd', or a memory type, and return every rule.

```json
{
  "description": "Add a show-less rule for one of the caller's own people or pets, a date written as 'MM-dd', or a memory type, and return every rule.",
  "operationId": "addMemoryShowLess",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryShowLessDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/MemoryShowLessResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Show less of a person, pet, date or kind of memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.update"
}
```

## Retrieve memories statistics

GET /api/memories/statistics

Retrieve statistics about memories, such as total count and other relevant metrics.

```json
{
  "description": "Retrieve statistics about memories, such as total count and other relevant metrics.",
  "operationId": "memoriesStatistics",
  "parameters": [
    {
      "name": "for",
      "required": false,
      "in": "query",
      "description": "Filter by date",
      "schema": {
        "format": "date",
        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
        "example": "2024-01-01",
        "type": "string"
      }
    },
    {
      "name": "id",
      "required": false,
      "in": "query",
      "description": "Memory ID",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    },
    {
      "name": "isHidden",
      "required": false,
      "in": "query",
      "description": "Only the memories the owner hid (true); hidden memories are left out otherwise",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isSaved",
      "required": false,
      "in": "query",
      "description": "Filter by saved status",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isTrashed",
      "required": false,
      "in": "query",
      "description": "Include trashed memories",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "isUpcoming",
      "required": false,
      "in": "query",
      "description": "Filter by memories that have not been shown yet",
      "schema": {
        "type": "boolean"
      }
    },
    {
      "name": "order",
      "required": false,
      "in": "query",
      "schema": {
        "$ref": "#/components/schemas/MemorySearchOrder"
      }
    },
    {
      "name": "page",
      "required": false,
      "in": "query",
      "description": "Page number",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "type": "integer"
      }
    },
    {
      "name": "size",
      "required": false,
      "in": "query",
      "description": "Number of memories to return",
      "schema": {
        "minimum": 1,
        "maximum": 9007199254740991,
        "type": "integer"
      }
    },
    {
      "name": "type",
      "required": false,
      "in": "query",
      "schema": {
        "$ref": "#/components/schemas/MemoryType"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryStatisticsResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve memories statistics",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.statistics"
}
```

## Delete a memory

DELETE /api/memories/{id}

Delete a specific memory by its ID.

```json
{
  "description": "Delete a specific memory by its ID.",
  "operationId": "deleteMemory",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "204": {
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Delete a memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.delete"
}
```

## Retrieve a memory

GET /api/memories/{id}

Retrieve a specific memory by its ID.

```json
{
  "description": "Retrieve a specific memory by its ID.",
  "operationId": "getMemory",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Retrieve a memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.read"
}
```

## Update a memory

PUT /api/memories/{id}

Update an existing memory by its ID.

```json
{
  "deprecated": true,
  "description": "Update an existing memory by its ID.",
  "operationId": "updateMemory",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryUpdateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Update a memory",
  "tags": [
    "Memories",
    "Deprecated"
  ],
  "x-frameleaf-permission": "memory.update"
}
```

## Remove assets from a memory

DELETE /api/memories/{id}/assets

Remove a list of asset IDs from a specific memory.

```json
{
  "description": "Remove a list of asset IDs from a specific memory.",
  "operationId": "removeMemoryAssets",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BulkIdsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Remove assets from a memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memoryAsset.delete"
}
```

## Add assets to a memory

PUT /api/memories/{id}/assets

Add a list of asset IDs to a specific memory.

```json
{
  "description": "Add a list of asset IDs to a specific memory.",
  "operationId": "addMemoryAssets",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/BulkIdsDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "200": {
      "content": {
        "application/json": {
          "schema": {
            "items": {
              "$ref": "#/components/schemas/BulkIdResponseDto"
            },
            "type": "array"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Add assets to a memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memoryAsset.create"
}
```

## Export a memory

POST /api/memories/{id}/exports

Start a private highlight export of a memory's assets as a durable, cancellable background job. The asset list is snapshotted when the export starts, and a second request while one is already running returns the export in flight.

```json
{
  "description": "Start a private highlight export of a memory's assets as a durable, cancellable background job. The asset list is snapshotted when the export starts, and a second request while one is already running returns the export in flight.",
  "operationId": "createMemoryExport",
  "parameters": [
    {
      "name": "id",
      "required": true,
      "in": "path",
      "schema": {
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$",
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryExportCreateDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/MemoryExportResponseDto"
          }
        }
      },
      "description": ""
    }
  },
  "security": [
    {
      "api_key": []
    }
  ],
  "summary": "Export a memory",
  "tags": [
    "Memories"
  ],
  "x-frameleaf-permission": "memory.update"
}
```