Restoring an Aetherfy collection

An Aetherfy restore brings a collection back from a restore point into a new collection. It works the same whether the collection still exists (its points are wrong) or was deleted (you want it back). The collection a restore point is a copy of is never changed: you compare the new collection with it and keep whichever is right.

What an Aetherfy restore point is

A restore point is a copy of a collection that you can restore from. A collection has up to two kinds:

• The copy taken when it was deleted. Deleting a collection, whoever does it, a person or an agent, frees its name, its slot and its storage at once, but Aetherfy backs it up first, before any of its data is dropped, and keeps that copy for your plan’s window, counted from when the copy was ready. Every plan has it. If the copy cannot be taken, the data is kept and Aetherfy looks at it: a delete is never turned into a loss.
• A daily copy. Aetherfy backs up every collection once a day, and each day’s copy is a restore point for as many days back as your plan reaches. A plan with no daily copies (Free) has only the copy taken at a deletion.

How many days each plan keeps and reaches, and how many restores a calendar month allows, is on the platform limits page and nowhere else; this page names the limits and does not copy them.

A restore point has an id. A list gives it and a restore takes it back; treat it as opaque. A copy taken at a deletion has a UUID; a daily copy has day_<collection id>_<date>. It is never a name: two deleted collections can have had the same one. An id that is another account’s, malformed, outside your plan’s days or with no copy behind it is the same 404 COLLECTION_BACKUP_NOT_FOUND.

A worked example of an Aetherfy restore

Your agents read the collection products through the alias products-live. On 30 October a script overwrites half of its payloads. The daily copy of 27 October is still good.

List the restore points of products:

afy collections restore-points products --workspace shop

Restore the copy of 27 October. products is live, so its old name is taken and the new collection is called products-2026-10-27:

afy collections restore day_3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10_2026-10-27 --workspace shop --wait

Look at products-2026-10-27: its points, a few payloads. When it is right, move the alias to it in one batch, so your agents change collection with no downtime:

curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/shop/aliases \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actions":[{"create_alias":{"alias_name":"products-live","collection_name":"products-2026-10-27"}}]}'

products is untouched, so you can compare, or move the alias back. Delete it when you no longer need it.

Why a new collection. A restore never goes over a live collection, because overwriting would destroy today’s data, including what was written correctly since that day. A name that a collection or an alias already has in the workspace is refused with COLLECTION_NAME_TAKEN_FOR_RESTORE and nothing is overwritten.

Restoring a deleted Aetherfy collection

A deleted collection has the copy taken at its deletion, and its daily copies stay restorable for the days your plan reaches. List the workspace’s deleted collections, with their ids:

afy collections restore-points --workspace shop

Restoring the copy taken at the deletion brings the collection back under its old name when that is free (otherwise as <name>-<date>), with its payload schema and its aliases:

afy collections restore 3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10 --wait

The gap. The copy taken at a deletion is the collection as it was when it was deleted. If it was damaged before that, the copy is the damaged state. The daily copies from before the damage are the way back, and a deleted collection has them too. List both kinds by the collection’s id, which the list of deleted collections shows:

afy collections restore-points --collection-id 3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10

A daily copy is as of the day it was taken, so writes after it, up to the deletion, are only in the copy taken at the deletion. A collection created and deleted between two daily copies has only the copy taken at its deletion. When both matter, restore both under different names and compare.

What comes back from an Aetherfy restore

Both kinds bring back the points (ids, vectors and payloads), the payload indexes, the description, the vector size and distance, and the regions the collection had, in the same workspace. The workspace must still cover those regions.

• The payload schema comes back as it was. For a daily copy it is the schema the collection had on that day, even when it has changed since; a collection that had none that day comes back with none.
• Aliases are not copied from a daily copy. An alias names exactly one collection and the live collection still holds its own; copying them would make two collections answer to one alias, and moving them would silently send live traffic to old data. Move them yourself after you have checked the restore, as in the example above. The copy taken at a deletion does bring its aliases back, because nothing else holds them.
• The restored collection is a full collection. It is on your collections list, counts toward your plan’s collection limit and storage like any other, and is backed up from the next daily pass.

The Aetherfy restore allowance is one

A calendar month (UTC) allows a number of restores and a volume restored, at most the plan’s storage size. There is one count and one volume for both kinds of restore point and all your collections: a restore of a daily copy and a restore of a deleted collection draw on the same ones. A restore that fails is not counted. A restore is also a create, so the plan’s collection limit and storage limit apply. Every list tells what is left this month in its allowance, and the message of a refusal gives the date a monthly limit resets.

A plan limit is the vector API’s one body, with error.code PLAN_LIMIT_EXCEEDED, and error.limit names which: collection_backup_restore_days (a daily copy on a plan with no daily copies), collection_restores_per_month, max_storage_bytes or max_collections.

A daily Aetherfy copy is as of a range of times

A collection’s shards are copied one after another, so the points of one day’s copy were read at different times. Each daily restore point shows when its first and its last shard were taken (taken_from and taken_to). A small collection is taken within seconds; a large one can take hours, and the restored collection mixes points from across that range. Read the range before you restore.

Aetherfy takes the shards of the daily pass in the order of collection, then shard, with no copy slot idle, which narrows the range of a large collection. That comes from a simulation of the copy pace, not from a measurement on the live fleet, and the real range depends on how fast the nodes snapshot. Making the range only the snapshot time, by snapshotting every shard of a collection before uploading any, is not built: it needs room on a collection’s nodes for all of its snapshots at once.

Aetherfy restore routes

These routes are for people. An Aetherfy agent’s key is refused with 403 AUTH_AGENT_KEY_OUT_OF_SCOPE. A restore point is addressed by its own id, and a collection by its id, never by name, except the list of a live collection under its workspace:

Each restore point has its kind (daily or deletion), the collection it is of (its id, name and whether it is deleted), when it was taken_at, its points, bytes, regions and status. A daily copy also has its day, taken_from and taken_to. A copy taken at a deletion also has deleted_by ({"kind": "person"}, or an agent by its id) and expires_at. The status is ready, backing_up (a copy taken at a deletion that is still being taken), unavailable (it could not be completed; its data is kept and support can retry it) or restoring.

A restore answers 202 at once and runs in the background, region by region. The new collection is available when every region it lives in (one on a Free or Starter plan) has its copy; regions_ready out of regions_total shows the progress, and the restore_id of the 202 is the id to follow. A restore that fails removes the new collection and leaves the restore point and the live collection as they were; it can be restored again. Until it finishes, creating a collection under the name it holds answers 409 COLLECTION_BEING_RESTORED. Without as the name is the first free of the collection’s old name and the old name with the point’s date (<name>-<date>).

curl -s "https://vectors.aetherfy.com/api/v1/restore-points?collection_id=$COLLECTION_ID" \
  -H "Authorization: Bearer $AETHERFY_API_KEY"
 
curl -s -X POST https://vectors.aetherfy.com/api/v1/restore-points/$POINT_ID/restore \
  -H "Authorization: Bearer $AETHERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"as": "products-2026-10-27"}'

Aetherfy restore errors

Restoring an Aetherfy collection from the CLI

afy collections restore-points products --workspace shop
afy collections restore-points --workspace shop
afy collections restore-points --collection-id 3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10
afy collections restore day_3f2b0c1e-0c61-4c0e-9b53-2f9f6a7a4d10_2026-10-27 --as products-before --workspace shop --wait

afy collections restore-points lists, in one of three ways: a live collection by name, the workspace’s deleted collections (no argument), or one collection by its id (--collection-id), live or deleted. afy collections restore takes a restore point’s id and starts the restore; --as names the new collection and --wait follows it (the CLI reference).

Restoring an Aetherfy collection from the dashboard

The RESTORE tab of a collection lists its restore points, each with the range it was taken in. RESTORE opens a dialog that says what comes back and asks for the name of the new collection (the database page). On Free the tab says the plan has no daily copies. A workspace’s Recently deleted list shows its deleted collections with the same dialog, and DAILY COPIES on a row lists that collection’s daily copies from before it was deleted (workspaces).