Create a backup key
amber_create_backup_keyCreate a credential that lets automated jobs download full account backups without an AI session, and set a threshold for warning when scheduled backups stop succeeding.
Instructions
Create a key that lets an automated job download a full export of this account without an AI session -- for example a weekly cron that saves everything to the user's own S3 bucket or NAS.
Usage: a backup is a task. POST /backup with header X-Amber-Backup-Key: <key> returns a task_id; poll GET /backup/<task_id> with the same header until status is complete, then download the download_url it carries. A ready-to-run weekly script is at https://ambermem.com/backups
IMPORTANT: the key is shown ONCE and never again -- only a hash is stored, so it cannot be recovered, only replaced. RELAY IT TO THE USER VERBATIM and tell them to save it somewhere safe.
There is one key per account: calling this again REPLACES the previous key, which immediately stops working. That is how rotation works, and how to respond if a key leaks. The response says when the replaced key was last used, so you can tell the user whether a scheduled job just stopped -- RELAY THAT WARNING if it is there, because the job will not report the failure itself.
The key does exactly TWO things: download an export, and start a restore -- which is a WRITE, so treat it as more than a read credential. It cannot read an individual memory, change the subscription, or delete the account. Corrected 2026-09-19: this said "exactly one thing ... cannot read, write or delete anything", which understated it, and the tool's own response text said the opposite. A restore also puts trashed memories back AS trash, which is a change rather than an addition. The backup includes deleted memories still in the trash.
Backups are limited to one per hour. Revoke with amber_revoke_backup_key. Not rate-limited.
ASK THE USER how long a gap without a successful backup should be treated as a problem, and pass it as warn_after_days. Without it Amber has to fall back to a cautious 30 days, and a backup that stopped is invisible until the day it is needed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| warn_after_days | No | WARN THE USER WHEN NO BACKUP HAS SUCCEEDED FOR THIS MANY DAYS. It is the alert threshold itself, in days, used exactly as given: pass 10 and the warning appears once nothing has succeeded for 10 days. Nothing is multiplied or padded. WHY IT EXISTS. A backup that stops does not announce itself. The job receives an error and writes it to a log nobody reads, so the user goes on believing they have backups and finds out on the day they need one, which is the only day it cannot be fixed. Amber can see WHEN a backup last succeeded and nothing else. It cannot know when the next one is due, whether the machine is meant to be on, or whether the user is on holiday. So the line between 'quiet' and 'broken' has to come from them. HOW TO CHOOSE IT. Ask how often the job runs, then allow room for a missed run or two, and pass the RESULT. A nightly backup is comfortable at 3. The weekly script at the documented backup script is comfortable at 14 to 21. A monthly job wants 45 or more. Err high rather than low: a warning that fires on a healthy setup teaches the user to ignore the channel, and then the real one is ignored too. DO NOT pass the backup interval itself. `warn_after_days: 7` for a weekly job means a single missed run raises a warning, which for most people is a machine that was off for a night. WHEN AND WHERE IT FIRES. In the user's tool responses, at most once a day, and it clears itself the moment a backup succeeds again. There is nowhere else it can go: Amber holds no email address for anybody, by design. Relay it when you see it, because it is addressed to the user and they will not see it otherwise. IT IS NOT THE ONLY CHECK. If something presents a backup key that was replaced or revoked, the user is told on their next message regardless of this number, and told what to fix. This threshold is the net that catches everything else: a dead machine, a disabled schedule, a full disk, an edited script. IF YOU LEAVE IT OUT. Nothing breaks. An existing value is KEPT, so rotating a key does not silently widen the window. With no value at all Amber warns after 30 days. Prefer asking: for a nightly backup the default is a month of loss before anybody says anything. CHANGING IT LATER means calling this tool again, which also REPLACES the key and forces the user to update their job. Ask now rather than revisiting it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | A human-readable summary, including the replacement warning when there is one. | |
| backup_key | Yes | The key itself, shown ONCE and never recoverable. Relay it to the user verbatim and tell them to save it. | |
| example_command | Yes | A ready-to-run curl that starts a backup with this key. Safe to show. | |
| warn_after_days | Yes | The backup-silence threshold now in force, in days: you are warned when no backup has succeeded for this many days. Echoed because creating a key is the only way to SET it, and a rotation that omits it deliberately carries the previous value forward -- so this is where you find out what you are on. Null means the server default applies. | |
| replaced_existing | Yes | True if this call revoked a previous key. Anything still using that key stops working immediately. | |
| replaced_key_last_used_at | Yes | When the key this call just revoked was last used successfully, or null if it was never used (or there was none). NOT trivia: a recent timestamp means a scheduled job was relying on it and has just stopped, and that job will not report the failure itself. WARN THE USER when this is set. |