Aetherfy vector REST API
Base URL and authentication for the Aetherfy vector API
The Aetherfy vector API is served from https://vectors.aetherfy.com. Every
customer-facing route lives under /api/v1. Authentication is a bearer token:
Authorization: Bearer <api key>A request with no Authorization header, or one that is not a Bearer header,
is refused with 401 MISSING_API_KEY. A syntactically valid key that does not
resolve is refused with 401 INVALID_API_KEY. All error shapes are documented on
errors.
Every Aetherfy collection lives in a workspace
A collection always belongs to one of your workspaces, and every collection route names that workspace first. There are two ways to name it, and every route below accepts both:
| Prefix | Names the workspace | Who uses it |
|---|---|---|
/api/v1/workspaces/{workspace} | By its name | People, scripts, the CLI |
/api/v1/workspace-ids/{workspace_id} | By its id (a UUID) | An agent: the SDKs’ workspace="auto" reads the agent’s AETHERFY_WORKSPACE_ID and uses this form |
The tables below write that prefix as {ws}, so {ws}/collections/{name} means
/api/v1/workspaces/{workspace}/collections/{name} or
/api/v1/workspace-ids/{workspace_id}/collections/{name}. Every account starts
with a workspace named default, which the examples on this page use.
curl -s https://vectors.aetherfy.com/api/v1/workspaces/default/collections \
-H "Authorization: Bearer $AETHERFY_API_KEY"The workspace is looked up within your account only. One that does not exist is
404 WORKSPACE_NOT_FOUND (with workspace, or workspace_id echoed as you sent
it), and another account’s workspace id gets exactly that same answer: nothing
of another account is ever read, changed or named. To an agent’s key, a
workspace it was not granted is 403 AGENT_KEY_WORKSPACE_FORBIDDEN, whether or
not it exists (see what an agent’s key reaches).
If the workspace cannot be looked up at all, the answer is 503
WORKSPACE_LOOKUP_UNAVAILABLE, which is safe to retry.
A path with no workspace in front is refused with 400 WORKSPACE_REQUIRED,
whose message names the form to use. That covers every /api/v1/collections...
path (the list and create included), /api/v1/aliases, and /api/v1/schema/....
Collection names in a path are your own bare names. Aetherfy builds the names it
stores internally, and a request that carries one of those internal forms is
refused before anything is looked up: 400 WORKSPACE_REQUIRED without a
workspace in front, 400 INVALID_COLLECTION_NAME inside a workspace route.
Aetherfy collection names
| Rule | Detail |
|---|---|
| Characters | [a-zA-Z0-9_-], 1 to 100 of them. Longer in a path is 400 VALIDATION_ERROR; any other break is 400 INVALID_COLLECTION_NAME |
| Reserved prefix | A collection or alias name may not begin user_; the prefix is reserved for internal names. 400 INVALID_COLLECTION_NAME (INVALID_ALIAS_NAME for an alias) |
| Unique per workspace | Two workspaces may each have an articles; they are two collections. Within one workspace a name is a collection or an alias, never both |
Collection routes in the Aetherfy vector API
| Method | Path | Purpose |
|---|---|---|
| POST | {ws}/collections | Create a collection. Body: {name, vectors:{size,distance}, description?, regions?} |
| GET | {ws}/collections | List this workspace’s collections |
| GET | {ws}/collections/{name} | Collection info |
| PATCH | {ws}/collections/{name} | Rename it, change its description, or both. Body: {name?, description?} |
| DELETE | {ws}/collections/{name} | Delete the collection; it is backed up first and can be restored for your plan’s window |
On create, regions must be within the workspace’s regions, and left out the
collection gets all of them. Re-creating a live name in the same workspace is
idempotent and returns 200 {"result": true, "status": "ok", "regions": [...]},
whatever configuration it asks for, so a script may create unconditionally on
every run. Creating a collection under the name of an alias in the same
workspace is 409 COLLECTION_NAME_IS_AN_ALIAS. A workspace with no regions is 400
WORKSPACE_HAS_NO_REGIONS: set its regions in the dashboard or with
afy workspaces regions <name>.
Aetherfy fixes the rest of the collection configuration server-side. There is no
request field for optimizers_config, hnsw_config, or any other engine tuning
at creation time.
A collection holds one unnamed vector per point: vectors is exactly {"size": 1 to 65536, "distance": "Cosine" | "Euclid" | "Dot" | "Manhattan"} (the distance in any case), and named vectors, any other key, or a size or distance outside those are refused with 400 VALIDATION_ERROR, field: "vectors".
Descriptions are at most 500 characters and may not contain HTML angle brackets; either violation returns 400.
Nothing refuses a delete because an agent used the collection: the delete is
yours to make. Before you do, afy collections delete tells you which agents used
it in the last 35 days, from what Aetherfy observes them reading and writing (there
is nothing to declare). An agent’s own key deletes a collection only at
full access, and never one that
is protected.
# Create.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"articles","vectors":{"size":4,"distance":"Cosine"},"description":"Article embeddings"}'
# Read.
curl -s https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles \
-H "Authorization: Bearer $AETHERFY_API_KEY"
# Change the description.
curl -s -X PATCH https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"description":"Article embeddings, v2"}'
# Delete.
curl -s -X DELETE https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles \
-H "Authorization: Bearer $AETHERFY_API_KEY"Renaming an Aetherfy collection
PATCH {ws}/collections/{name} with name renames the collection within its
workspace. Send name, description, or both; an empty body or any other key
is 400 VALIDATION_ERROR. The answer is
{name, description, config, status, updated_at} with the new name, and a
name equal to the current one changes nothing and answers the same 200.
curl -s -X PATCH https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"articles-2025"}'Code that uses the old name stops finding it: after a rename the old name is
404 COLLECTION_NOT_FOUND. Everything else stays: the collection’s id, its data,
its aliases (they point at the collection, not at its name), its schema and its
regions. The rename is seen at once in the region that served it and within 60
seconds in your other regions. To move a collection to another workspace, see
moving a collection.
Renaming is for people. An agent’s key that sends name is refused with 403
AUTH_AGENT_KEY_OUT_OF_SCOPE and nothing changes; an agent at full may still change a
description. The SDKs have no rename: use the dashboard, afy collections update --name, or this route with a key you created.
| Refusal | HTTP | When |
|---|---|---|
AUTH_AGENT_KEY_OUT_OF_SCOPE | 403 | An agent’s key sent name |
VALIDATION_ERROR | 400 | The new name is over 100 characters (field: "name") |
INVALID_COLLECTION_NAME | 400 | The new name breaks the name rule or begins user_ |
ADDRESSED_AN_ALIAS | 409 | The path names an alias: rename the collection by its own name |
COLLECTION_NOT_FOUND | 404 | No such collection |
COLLECTION_SDK_MANAGED | 422 | The collection is the memory SDK’s __threads__, or the new name begins __threads__ |
COLLECTION_NAME_TAKEN | 409 | The new name is already a collection or an alias in this workspace; taken_by says which (collection or alias) |
Response headers and body on an Aetherfy collection read
GET {ws}/collections/{name} returns a body of the form
{result, schema_version} and carries three response headers that Aetherfy adds:
| Header | Meaning |
|---|---|
ETag | Version tag for the collection record |
X-Collection-Source | Which store answered the read |
X-Collection-Status | Lifecycle status of the collection |
These headers are specific to the single-collection read on Aetherfy; the list route does not carry them.
result carries id, the collection’s UUID, which stays the same across a
rename and a move, beside its name, description, config, points_count,
status, regions, created_at and updated_at. It also carries the
collection’s payload indexes, as Qdrant’s payload_schema
({field: {data_type, params?, points}}), and payload_schema_region, the
region whose Qdrant reported them. Aetherfy builds an index in each of a
collection’s regions on its own clock, so the indexes are that region’s. A
region that does not hold the collection answers null for both, which means
the indexes cannot be read there, not that there are none; a collection with no
indexes answers {}.
Point routes in the Aetherfy vector API
| Method | Path | Purpose |
|---|---|---|
| PUT | {ws}/collections/{name}/points | Upsert points (streaming). Body: {"points":[{id, vector, payload?}]} |
| POST | {ws}/collections/{name}/points/query | Similarity search. Body: {query:[...], limit?, offset?, filter?, with_payload?, with_vector?, score_threshold?, params?, prefetch?}; matches in result.points |
| POST | {ws}/collections/{name}/points/query/batch | Several searches: {searches:[...]}, up to 100 |
| POST | {ws}/collections/{name}/points/query/groups | Search grouped by a payload field (group_by) |
| POST | {ws}/collections/{name}/points/retrieve | Retrieve by ids. Body: {ids:[...], with_payload?, with_vector?} |
| GET | {ws}/collections/{name}/points/{id} | Retrieve a single point |
| POST | {ws}/collections/{name}/points/scroll | Paginate through points |
| POST | {ws}/collections/{name}/points/count | Count. Body: {filter?, exact?} |
| POST | {ws}/collections/{name}/points/delete | Delete by {points:[ids]} or by {filter:{...}} |
Upsert on Aetherfy is PUT, not POST. This is the single most common mistake
against this API — see the unsupported-endpoint section below for what POST on
that path actually does.
Search is /points/query. Qdrant’s older search routes — /points/search,
/points/recommend, /points/discover, and their /batch and /groups forms —
answer 410 ROUTE_RETIRED, with the route to use in the body’s
replacement. A query body without query is not an error: it lists points
unranked, each scored 1.0.
On the retrieve route the flags are with_payload (default true) and
with_vector — singular — defaulting to false. The query body takes the same
singular spelling, with_vector. Both Aetherfy SDKs expose this option under the
plural name (with_vectors in Python, withVectors in JavaScript), so a
hand-written REST query body that says with_vectors is not a flag Aetherfy
reads. On the count route a limit
key in the body is stripped by Aetherfy before the request reaches the engine, so
sending one has no effect.
A collection that does not exist is 404 COLLECTION_NOT_FOUND, answered before
anything reaches the storage engine. A point the collection does not hold, on
the routes that read or change one point (GET .../points/{id}, the payload
routes), is 404 NOT_FOUND, with the engine’s own text as the message.
# Upsert (PUT, not POST).
curl -s -X PUT https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"points":[
{"id":1,"vector":[0.1,0.2,0.3,0.4],"payload":{"lang":"en"}},
{"id":2,"vector":[0.4,0.3,0.2,0.1],"payload":{"lang":"fr"}}
]}'
# Search.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/query \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":[0.1,0.2,0.3,0.4],"limit":5,"with_payload":true}'
# Retrieve by id.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/retrieve \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids":[1,2],"with_payload":true,"with_vector":false}'
# Retrieve a single point.
curl -s https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/1 \
-H "Authorization: Bearer $AETHERFY_API_KEY"
# Scroll.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/scroll \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"limit":100,"with_payload":true}'
# Count.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/count \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"exact":true}'
# Delete by id, then by filter.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/delete \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"points":[1,2]}'
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/delete \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filter":{"must":[{"key":"lang","match":{"value":"fr"}}]}}'Per-request caps on these routes — search and scroll limit, retrieve id count,
delete point count, upsert point count and wire size — are on
limits.
Reading from another of your collections in the Aetherfy vector API
Two query-body fields make the engine read a second collection:
| Field | Routes | What it does |
|---|---|---|
lookup_from | points/query, each of points/query/batch’s searches, points/query/groups, and every prefetch at any depth | {"collection": "<name>"}: point ids in query are turned into vectors from that collection instead of this one |
with_lookup | points/query/groups | A collection name, or {"collection": "<name>", "with_payload": ..., "with_vectors": ...}: each group’s id is looked up in that collection and returned as the group’s lookup |
The collection is named in one of two forms:
| Value | Means |
|---|---|
name | The collection name in the workspace the URL names |
workspace/name | The collection name in another of your workspaces, by its name. An agent’s key must have been granted that workspace, exactly as if it addressed it directly |
Anything else (a number, a list, an empty string, a third /, an id form, a
name beginning user_) is 400 VALIDATION_ERROR. A failure names the body
field it came from in field: an unknown workspace is 404 WORKSPACE_NOT_FOUND
(403 AGENT_KEY_WORKSPACE_FORBIDDEN to an agent’s key), an unknown collection
404 COLLECTION_NOT_FOUND, and a lookup that cannot be made right now 503
WORKSPACE_LOOKUP_UNAVAILABLE or PLACEMENT_UNAVAILABLE. An alias works here as
its collection. with_lookup spells its vector flag with_vectors, plural,
unlike the singular with_vector of the query body. The SDKs do not expose
either field; send them through the REST API.
# Search "articles" with the vector point 42 has in this workspace's "embeddings".
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/query \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":42,"lookup_from":{"collection":"embeddings"},"limit":5,"with_payload":true}'
# Group "chunks" by doc_id and return each group's document from "documents".
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/chunks/points/query/groups \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":[0.1,0.2,0.3,0.4],"group_by":"doc_id","limit":3,"with_lookup":{"collection":"documents","with_payload":true,"with_vectors":false}}'
# The lookup collection lives in your workspace "team-alpha".
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/query \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":42,"lookup_from":{"collection":"team-alpha/embeddings"},"limit":5}'Payload and index routes in the Aetherfy vector API
| Method | Path | Purpose |
|---|---|---|
| POST | {ws}/collections/{name}/points/payload | Set payload — merge |
| PUT | {ws}/collections/{name}/points/payload | Overwrite payload — replace |
| POST | {ws}/collections/{name}/points/payload/delete | Delete named payload keys |
| PUT | {ws}/collections/{name}/index | Create a payload field index (POST is 405) |
| DELETE | {ws}/collections/{name}/index/{field} | Delete a payload field index |
POST merges into the existing payload; PUT replaces it wholesale. Aetherfy
reserves every payload key beginning __aetherfy_ and strips them from read
responses, with two exceptions: __aetherfy_agent_id and
__aetherfy_deployment_id, the attested author and deployment described below,
come back on every read. Because they come back you may send them again —
Aetherfy ignores the values and re-stamps them from your credential. Sending any
of the others returns 400 RESERVED_FIELD.
An overwrite with key is refused with 400 KEYED_OVERWRITE_NOT_SUPPORTED, because the vector store would replace the whole payload rather than the value under key; to change a nested value, use POST with key.
# Merge keys into the existing payload.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/payload \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"payload":{"reviewed":true},"points":[1,2]}'
# Replace the payload wholesale.
curl -s -X PUT https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/payload \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"payload":{"lang":"en"},"points":[1]}'
# Remove named keys.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/payload/delete \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":["reviewed"],"points":[1,2]}'Attested authorship in the Aetherfy vector API
Every point the Aetherfy vector API returns carries two keys in its payload that
record the credential that performed the write: __aetherfy_agent_id, which
agent, and __aetherfy_deployment_id, which of that agent’s deployments.
| Credential used for the write | __aetherfy_agent_id | __aetherfy_deployment_id |
|---|---|---|
| An API key Aetherfy minted and injected into an agent at deploy | That agent’s id | The deployment that wrote it; for a task agent, the run |
| An API key you created yourself | null | null |
| The Aetherfy dashboard’s vector explorer | null | null |
The two are set together: __aetherfy_deployment_id is null exactly when
__aetherfy_agent_id is. The deployment identifies a version of the agent, not
a machine or a region. Every machine of one service deployment stamps the same
id, and each task run stamps its own.
Aetherfy sets both values from the credential on every write. You may send the
keys back — you have to be able to, since they come out on every read and
editing a payload means retrieving it, changing a field and writing it again.
Aetherfy ignores whatever values you send and stamps the credential’s. Sending
them is never an error, and choosing their values is never possible: an agent
that names its own id or deployment gets the same treatment as one that names
somebody else’s, and a key you created yourself always stamps null for both no
matter what the body says. Both are attested by Aetherfy rather than asserted
by the client precisely because Aetherfy issued the agent’s credential for that
deployment and nobody else could have used it.
The other reserved keys behave differently, because they never come back on a
read: sending one is rejected with 400 RESERVED_FIELD.
Both keys are re-evaluated on every mutation. An upsert, a payload set or overwrite, a payload-key delete, a payload clear and a vector update or delete all re-attribute the point to whoever performed that write — the same last-writer rule Aetherfy uses to order writes across regions.
Aetherfy records who made a write in the same request as the write. A payload
set, an overwrite and a payload clear are one operation, so a filter on them
selects the points once and the record lands on exactly those points. A keyed
set (with key), a payload-key delete and a vector delete are two steps — your
change, and the record of who made it — and each selects with your filter (a
vector update is two steps as well, by point id only). When the write picks its
points with a filter instead of point ids,
Aetherfy orders the two so that both reach exactly the points the filter
selected before the write, whether the key is yours or an agent’s:
| The filter tests | What Aetherfy does |
|---|---|
A key the write changes, such as status in a delete of status, or the vector a vector delete removes | Records the author first, then makes your change |
__aetherfy_agent_id or __aetherfy_deployment_id | Makes your change first, then records the author |
| Neither | Makes your change, then records the author |
| Both | Refuses the write with 400 AMBIGUOUS_FILTERED_WRITE; nothing is applied |
On these two-step writes a filter with a shape Aetherfy does not recognise is refused the same way, rather than guessed at. To make such a change, edit the points by id, or split the request so that each part’s filter tests only one of the two.
Unlike Aetherfy’s other reserved keys, these two are returned on search, retrieve and scroll, and you can filter on either:
# Everything a given agent wrote.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/points/scroll \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filter":{"must":[{"key":"__aetherfy_agent_id","match":{"value":"6f1c…"}}]},"limit":20,"with_payload":true}'Aetherfy does not create a payload index for these keys. An unindexed filter is scanned rather than looked up, so if you filter by author or deployment routinely, index the key yourself through the index route above. More filter forms, including “written by any agent” and “written by one deployment”, are on filtering.
To tell agent-written points from yours, test the author with is_empty, never
is_null: a point written with one of your own keys may hold no author key at
all, because the payload merge cannot store a null, and is_empty matches a
missing key and a null alike. Reads still return the key as null.
Schema routes in the Aetherfy vector API
A payload schema belongs to its collection, so its routes sit under the collection:
| Method | Path | Purpose |
|---|---|---|
| GET | {ws}/collections/{name}/schema | Read the stored payload schema |
| PUT | {ws}/collections/{name}/schema | Write it. Body: {schema, enforcement_mode?, description?} |
| DELETE | {ws}/collections/{name}/schema | Remove it |
| POST | {ws}/collections/{name}/schema/analyze | Infer a schema from stored points. Body: {sample_size?} |
The old /api/v1/schema/{collection} routes answer 400 WORKSPACE_REQUIRED.
Addressed through an alias, a schema write or delete is 409
ADDRESSED_AN_ALIAS and a read or analyze is 404
COLLECTION_NOT_FOUND: a schema is the collection’s own, so name the
collection.
enforcement_mode accepts "off", "warn", or "strict"; anything else returns
400 INVALID_ENFORCEMENT_MODE. A schema that is not a valid payload schema is
400 INVALID_SCHEMA. sample_size on analyze must be an integer between 100
and 10 000, or Aetherfy returns 400 INVALID_SAMPLE_SIZE.
Enforcement applies to new writes only, so a schema you switch on says nothing about the points already stored: they are never checked against it.
The PUT route supports If-Match for compare-and-set. A stale ETag returns 412
SCHEMA_VERSION_MISMATCH, whose body carries current_etag and provided_etag,
and nothing changes. So does an If-Match for a collection that has no schema
any more (it was deleted since you read it): current_etag is null and nothing
is created. Re-read, and retry. Without If-Match the last write wins, and a
first schema is always written without it.
# Read the current schema.
curl -s https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/schema \
-H "Authorization: Bearer $AETHERFY_API_KEY"
# Infer one from the stored points.
curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/schema/analyze \
-H "Authorization: Bearer $AETHERFY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"sample_size":500}'
# Remove it.
curl -s -X DELETE https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles/schema \
-H "Authorization: Bearer $AETHERFY_API_KEY"Region discovery in the Aetherfy vector API
GET /api/v1/regions returns the region-to-regional-URL map that the Aetherfy
SDKs use to build a region-pinned client.
curl -s https://vectors.aetherfy.com/api/v1/regions \
-H "Authorization: Bearer $AETHERFY_API_KEY"Which regions actually hold your data is a property of your plan and your
workspace, not of this route: Free and Starter workspaces are single-region, and
replication across regions begins at the plan named Performance. A
collection is placed within its workspace’s regions; asking for a region outside
them returns 422 COLLECTION_REGIONS_NOT_IN_SCOPE.
Collection aliases in the Aetherfy vector API
An alias is a second name for a collection in the same workspace. Point your code at the alias, and you can change which collection it means without changing the code: that is how you re-index with no downtime.
Re-indexing with no downtime
Your agents query articles-live, which is an alias of articles-v1. To
re-embed everything with a new model:
-
Build the new collection beside the old one. Create
articles-v2and fill it;articles-livekeeps servingarticles-v1the whole time.curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/collections \ -H "Authorization: Bearer $AETHERFY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"articles-v2","vectors":{"size":1536,"distance":"Cosine"}}' -
Swap the alias in one batch.
create_aliason an existing alias repoints it, and the whole batch applies or none of it does, so there is no moment whenarticles-livepoints at nothing.curl -s -X POST https://vectors.aetherfy.com/api/v1/workspaces/default/aliases \ -H "Authorization: Bearer $AETHERFY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"actions":[{"create_alias":{"alias_name":"articles-live","collection_name":"articles-v2"}}]}' -
Delete
articles-v1when nothing reads it any more.
Your agents never change their code, and never see a gap: a request through
articles-live is served by articles-v1 before the swap and by articles-v2
after it. The swap applies at once in the region that served it, and within 60
seconds in your other regions.
Alias routes
| Method | Path | Purpose |
|---|---|---|
| POST | {ws}/aliases | Apply a batch of alias changes. Body: {"actions": [...]} |
| GET | {ws}/aliases | List the workspace’s aliases, ordered by name |
| GET | {ws}/collections/{name}/aliases | List the aliases of one collection |
Each action is an object holding one of three keys. Every name is bare and in the URL’s workspace:
| Action | Fields | Effect |
|---|---|---|
create_alias | alias_name, collection_name | Point the alias at the collection. An alias that already exists is repointed |
delete_alias | alias_name | Remove the alias. The collection is untouched |
rename_alias | old_alias_name, new_alias_name | Give an alias a new name |
The batch answers {"result": true, "status": "ok"}. It is one transaction:
a refused action means nothing in the batch was applied. Both lists answer
{"result": {"aliases": [{"alias_name", "collection_name"}]}, "status": "ok"}.
curl -s https://vectors.aetherfy.com/api/v1/workspaces/default/aliases \
-H "Authorization: Bearer $AETHERFY_API_KEY"
curl -s https://vectors.aetherfy.com/api/v1/workspaces/default/collections/articles-v2/aliases \
-H "Authorization: Bearer $AETHERFY_API_KEY"| Refusal | HTTP | When |
|---|---|---|
INVALID_REQUEST | 400 | No actions, or an empty list |
VALIDATION_ERROR | 400 | An action that is not an object, of an unknown kind, or with a name that is not a string |
CROSS_SCOPE_ALIAS_NOT_ALLOWED | 400 | A name with a /: an alias and its collection always share a workspace |
INVALID_ALIAS_NAME | 400 | The alias name breaks the name rule or begins user_ |
COLLECTION_NOT_FOUND | 404 | The target collection does not exist in this workspace, or is itself an alias |
ALIAS_NOT_FOUND | 404 | A delete or rename of an alias that does not exist |
ALIAS_NAME_IS_A_COLLECTION | 409 | The alias would take the name of a collection in this workspace |
ALIAS_NAME_TAKEN | 409 | A rename onto another alias’s name |
Only those are alias routes: any other verb on {ws}/collections/{name}/aliases
is 405, and {ws}/aliases/{alias} is 404.
Using a collection through an alias
| Request through an alias | Answer |
|---|---|
| Points, index, streaming upsert, a body reference | Served on the collection the alias points at, as if you had named it |
| Delete or PATCH the collection; write or delete its schema | 409 ADDRESSED_AN_ALIAS: these act on a collection itself. Name the collection, or change the alias |
| Collection info, its alias list, its schema read or analyze | 404 COLLECTION_NOT_FOUND |
A write through an alias is replicated to the collection’s regions and counted against the collection’s points and storage, exactly as a write naming it.
Aliases when a collection moves
A collection’s aliases belong to the collection, so they move with it when
it moves to another workspace.
Names are unique per workspace, so a move is refused before anything starts if
the collection’s name, or one of its aliases’ names, is already taken in the
target workspace (409 COLLECTION_NAME_TAKEN, COLLECTION_NAME_IS_AN_ALIAS or
ALIAS_NAME_TAKEN).
The alias codes, with their statuses, are on errors.
What an Aetherfy collection delete keeps
A collection delete takes effect in every region the collection lives in (one on a
Free or Starter plan) within seconds. Until it has, a region can still accept a write
to the collection. Such a write is not replicated: if it reached the collection’s first
region, where its backup is taken, a restore brings it back; in any other region it is
removed with the collection. Once it has, the Aetherfy vector API stops serving the collection, and its
name, its slot in your plan and its storage are free. What it does not do is destroy
the data straight away. The collection’s points, vectors,
payloads, indexes, payload schema and aliases are backed up first, and the data is
dropped from every region it lives in (one on a Free or Starter plan) only when that
backup is verified. A delete of an empty
collection keeps nothing. If the backup cannot be taken, the data is kept and
Aetherfy looks at it; the delete is never turned into a loss. The backups of a TEST
key’s account (afy_test_...) are kept one day, whatever the plan says.
The copy is kept for your plan’s window, counted from when it is ready; the days each plan keeps are on the limits. If the plan is lowered, the shorter window applies to the copies already taken from that moment; if it is raised, copies already taken keep the window they were taken under. When the window ends the copy is deleted and cannot be restored. Deleting a workspace deletes the copies of its collections with it, and deleting an account deletes every copy of the account.
That copy is one of a collection’s restore points, which is how a deleted collection is
listed and restored, through /api/v1/restore-points (people only, never by name). Its
routes, the daily copies a collection also has, the allowance and the error codes are on
restoring a collection.
Distance values accepted by the Aetherfy vector API
Aetherfy accepts the four distance names in any case at collection creation and stores them capitalised.
| You send (any case) | Aetherfy stores and returns |
|---|---|
cosine | Cosine |
euclid | Euclid |
dot | Dot |
manhattan | Manhattan |
Every name round-trips: a collection reads back the name it was created with,
capitalised. euclidean is not a distance name; a create that sends it is
refused with 400 VALIDATION_ERROR, field: "vectors". Both SDKs’
DistanceMetric.EUCLIDEAN sends Euclid.
What the Aetherfy vector API stores: float32, and unit length under Cosine
Aetherfy stores every vector component as a 32-bit float (float32), whatever precision you send. A value read back can differ from the one you sent by float32 rounding, about one part in ten million.
A Cosine collection also normalises each vector to unit length when it is
written: the stored vector points the same way as the one you sent but its
magnitude is gone, so a point read back from a Cosine collection can differ from
the one you upserted by far more than rounding (a vector of length 5 comes back as
length 1). The distance is unaffected, because cosine similarity ignores magnitude.
Dot, Euclid and Manhattan collections do not normalise: they keep the
direction and the magnitude, to float32 precision. If you need the exact original
values back, keep them in the point’s payload, or choose a distance that does not
normalise and mind that it ranks by magnitude too.
Qdrant compatibility and forwarding in the Aetherfy vector API
Anything under {ws}/collections/{name}/points/** is forwarded to Qdrant by
Aetherfy with its body unchanged, except where the body names a collection:
those names are resolved in your account (see
reading from another of your collections).
That is why Qdrant’s filter DSL, point shapes, and query bodies work unchanged.
Filters are checked on the way through: the engine silently ignores some filter
keys it does not know (a range with only a misspelled bound matches every point),
so Aetherfy refuses an unrecognised key with 400 INVALID_FILTER, naming the key
and the nearest valid one. Filter syntax and the validation are on
filtering.
An upsert (PUT .../points) takes only the points array. Any other member of
its body, such as the conditional-upsert members update_filter and
update_mode, shard_key, ordering, or the column-oriented batch form of
Qdrant’s upsert, is refused with 400 INVALID_REQUEST_FIELD naming it: they are
not supported, and ignoring them would store a conditional upsert as an
unconditional one. A member whose value is null is read as absent and
accepted. If the member comes after points in the body, the points
before it have already been stored; upserts are idempotent, so send them again
without it.
The one consequence to internalise: Aetherfy validates the envelope (auth,
workspace, tenancy, caps, reserved keys), the keys of every filter, and the
member names of every request body that can hold a filter (search and query,
scroll, count, the writes by filter, the distance matrix), and Qdrant validates
the rest of the query. A member of such a body that the API does not have is
refused with 400 INVALID_REQUEST_FIELD, naming it and the nearest one. That
includes consistency, timeout, wait and ordering: they are query
parameters (?wait=true), not body members: sent in a body they have no effect,
so they are refused. Only member names are checked;
what a member holds that is no filter (params, a vector, a payload) is
Qdrant’s to validate.
The one second name the API takes is with_vectors for with_vector, on
search and query (also inside a batch) and on scroll, where it returns vectors;
on a grouped query it does nothing, and is refused.
Endpoints the Aetherfy vector API does not support
Aetherfy is Qdrant-compatible but not a Qdrant passthrough. These are refused, deliberately, and no amount of retrying will change the answer.
| Request | Result | Use instead |
|---|---|---|
| Any collection, alias or schema path with no workspace in front | 400 WORKSPACE_REQUIRED | /api/v1/workspaces/{workspace}/... or /api/v1/workspace-ids/{workspace_id}/... |
PUT or PATCH on Qdrant’s own collection path (a native create) | 405 METHOD_NOT_ALLOWED, naming the create route | POST {ws}/collections |
PATCH {ws}/collections/{name} with optimizers_config, hnsw_config, or any key other than name and description | 400 VALIDATION_ERROR | Only the name and description change |
POST {ws}/collections/{name}/points expecting upsert | Not upsert — falls through to Qdrant’s batch retrieve, which expects body.ids | PUT {ws}/collections/{name}/points |
POST {ws}/collections/{name}/points/batch (Qdrant’s batch update) | 405 METHOD_NOT_ALLOWED, nothing applied | One request per write: PUT .../points, POST .../points/delete, POST or PUT .../points/payload, POST .../points/payload/delete, POST .../points/payload/clear, PUT .../points/vectors, POST .../points/vectors/delete |
POST {ws}/collections/{name}/index | 405 METHOD_NOT_ALLOWED | PUT {ws}/collections/{name}/index |
| Qdrant’s alias routes | 404: aliases are Aetherfy records, and the engine holds none | POST {ws}/aliases |
| Snapshot endpoints | 404 “Unsupported endpoint” | — |
/telemetry, /metrics | 404 “Unsupported endpoint” | — |
/cluster, /locks, shard endpoints | 404 “Unsupported endpoint” | — |
| Collection creation with engine tuning fields | Not accepted — configuration is fixed server-side by Aetherfy | — |
A payload key beginning __aetherfy_, other than __aetherfy_agent_id and __aetherfy_deployment_id | 400 RESERVED_FIELD on write; stripped from reads | Choose another key |
A payload key __aetherfy_agent_id or __aetherfy_deployment_id | Accepted and ignored — Aetherfy stamps the attested author and deployment from your credential; returned on reads | Nothing; round-tripping a payload is expected |
Query-time tuning is the one engine knob Aetherfy does expose, and it goes in the
request body’s params field — see search tuning.