Memories API

Ask about this page View Markdown

Base URL: https://YOUR-SERVER/api. Send your API key in x-api-key where authentication is required. A key also needs the listed permission; your account's access rules still apply.

API guide · All endpoints · OpenAPI JSON

GET /memories — Retrieve memories
POST /memories — Create a memory
GET /memories/exports — Retrieve memory exports
DELETE /memories/exports/{id} — Delete a memory export
GET /memories/exports/{id} — Retrieve a memory export
POST /memories/exports/{id}/cancel — Cancel a memory export
GET /memories/exports/{id}/download — Download a memory export
POST /memories/exports/{id}/library — Save a memory highlight to the library
DELETE /memories/show-less — Remove a memories show-less rule
GET /memories/show-less — Retrieve memories show-less rules
POST /memories/show-less — Show less of a person, pet, date or kind of memory
GET /memories/statistics — Retrieve memories statistics
DELETE /memories/{id} — Delete a memory
GET /memories/{id} — Retrieve a memory
PUT /memories/{id} — Update a memory
DELETE /memories/{id}/assets — Remove assets from a memory
PUT /memories/{id}/assets — Add assets to a memory
POST /memories/{id}/exports — Export a memory

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.

Authentication: API key. Permission: memory.read.

Parameters

Name	Where	Required	Description
`for`	query	No	Filter by date
`id`	query	No	Memory ID
`isHidden`	query	No	Only the memories the owner hid (true); hidden memories are left out otherwise
`isSaved`	query	No	Filter by saved status
`isTrashed`	query	No	Include trashed memories
`isUpcoming`	query	No	Filter by memories that have not been shown yet
`order`	query	No
`page`	query	No	Page number
`size`	query	No	Number of memories to return
`type`	query	No

Parameter types, defaults and constraints

Field definitions: MemorySearchOrder, MemoryType

[
  {
    "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

Field definitions: MemoryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/MemoryResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.create.

Request body

Required.

Field definitions: MemoryCreateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MemoryCreateDto"
    }
  }
}

Responses

Field definitions: MemoryResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.read.

Parameters

Name	Where	Required	Description
`memoryId`	query	No	Only return exports of this memory

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: MemoryExportResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/MemoryExportResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Delete a memory export

DELETE /api/memories/exports/{id}

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

Authentication: API key. Permission: memory.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Retrieve a memory export

GET /api/memories/exports/{id}

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

Authentication: API key. Permission: memory.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: MemoryExportResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryExportResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: MemoryExportResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryExportResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

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.

Authentication: API key. Permission: memory.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: MemoryExportResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryExportResponseDto"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.update.

Request body

Required.

Field definitions: MemoryShowLessDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MemoryShowLessDto"
    }
  }
}

Responses

Field definitions: MemoryShowLessResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/MemoryShowLessResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.read.

Responses

Field definitions: MemoryShowLessResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/MemoryShowLessResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.update.

Request body

Required.

Field definitions: MemoryShowLessDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MemoryShowLessDto"
    }
  }
}

Responses

Field definitions: MemoryShowLessResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/MemoryShowLessResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Retrieve memories statistics

GET /api/memories/statistics

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

Authentication: API key. Permission: memory.statistics.

Parameters

Name	Where	Required	Description
`for`	query	No	Filter by date
`id`	query	No	Memory ID
`isHidden`	query	No	Only the memories the owner hid (true); hidden memories are left out otherwise
`isSaved`	query	No	Filter by saved status
`isTrashed`	query	No	Include trashed memories
`isUpcoming`	query	No	Filter by memories that have not been shown yet
`order`	query	No
`page`	query	No	Page number
`size`	query	No	Number of memories to return
`type`	query	No

Parameter types, defaults and constraints

Field definitions: MemorySearchOrder, MemoryType

[
  {
    "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

Field definitions: MemoryStatisticsResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryStatisticsResponseDto"
        }
      }
    },
    "description": ""
  }
}

Delete a memory

DELETE /api/memories/{id}

Delete a specific memory by its ID.

Authentication: API key. Permission: memory.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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": ""
  }
}

Retrieve a memory

GET /api/memories/{id}

Retrieve a specific memory by its ID.

Authentication: API key. Permission: memory.read.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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

Field definitions: MemoryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryResponseDto"
        }
      }
    },
    "description": ""
  }
}

Update a memory

PUT /api/memories/{id}

Update an existing memory by its ID.

Deprecated. Avoid this operation in new integrations; use the replacement supported by your server release.

Authentication: API key. Permission: memory.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: MemoryUpdateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MemoryUpdateDto"
    }
  }
}

Responses

Field definitions: MemoryResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryResponseDto"
        }
      }
    },
    "description": ""
  }
}

Remove assets from a memory

DELETE /api/memories/{id}/assets

Remove a list of asset IDs from a specific memory.

Authentication: API key. Permission: memoryAsset.delete.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: BulkIdsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BulkIdsDto"
    }
  }
}

Responses

Field definitions: BulkIdResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/BulkIdResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

Add assets to a memory

PUT /api/memories/{id}/assets

Add a list of asset IDs to a specific memory.

Authentication: API key. Permission: memoryAsset.create.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: BulkIdsDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BulkIdsDto"
    }
  }
}

Responses

Field definitions: BulkIdResponseDto

{
  "200": {
    "content": {
      "application/json": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/BulkIdResponseDto"
          },
          "type": "array"
        }
      }
    },
    "description": ""
  }
}

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.

Authentication: API key. Permission: memory.update.

Parameters

Name	Where	Required	Description
`id`	path	Yes	string

Parameter types, defaults and constraints

[
  {
    "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"
    }
  }
]

Request body

Required.

Field definitions: MemoryExportCreateDto

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MemoryExportCreateDto"
    }
  }
}

Responses

Field definitions: MemoryExportResponseDto

{
  "201": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/MemoryExportResponseDto"
        }
      }
    },
    "description": ""
  }
}

Frameleaf and the Frameleaf logo are Trademarks of Frameleaf Inc.