Skip to Content
Vector databaseREST API reference
Raw

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:

PrefixNames the workspaceWho uses it
/api/v1/workspaces/{workspace}By its namePeople, 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

RuleDetail
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 prefixA 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 workspaceTwo 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

MethodPathPurpose
POST{ws}/collectionsCreate a collection. Body: {name, vectors:{size,distance}, description?, regions?}
GET{ws}/collectionsList 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.

RefusalHTTPWhen
AUTH_AGENT_KEY_OUT_OF_SCOPE403An agent’s key sent name
VALIDATION_ERROR400The new name is over 100 characters (field: "name")
INVALID_COLLECTION_NAME400The new name breaks the name rule or begins user_
ADDRESSED_AN_ALIAS409The path names an alias: rename the collection by its own name
COLLECTION_NOT_FOUND404No such collection
COLLECTION_SDK_MANAGED422The collection is the memory SDK’s __threads__, or the new name begins __threads__
COLLECTION_NAME_TAKEN409The 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:

HeaderMeaning
ETagVersion tag for the collection record
X-Collection-SourceWhich store answered the read
X-Collection-StatusLifecycle 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

MethodPathPurpose
PUT{ws}/collections/{name}/pointsUpsert points (streaming). Body: {"points":[{id, vector, payload?}]}
POST{ws}/collections/{name}/points/querySimilarity search. Body: {query:[...], limit?, offset?, filter?, with_payload?, with_vector?, score_threshold?, params?, prefetch?}; matches in result.points
POST{ws}/collections/{name}/points/query/batchSeveral searches: {searches:[...]}, up to 100
POST{ws}/collections/{name}/points/query/groupsSearch grouped by a payload field (group_by)
POST{ws}/collections/{name}/points/retrieveRetrieve by ids. Body: {ids:[...], with_payload?, with_vector?}
GET{ws}/collections/{name}/points/{id}Retrieve a single point
POST{ws}/collections/{name}/points/scrollPaginate through points
POST{ws}/collections/{name}/points/countCount. Body: {filter?, exact?}
POST{ws}/collections/{name}/points/deleteDelete 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:

FieldRoutesWhat it does
lookup_frompoints/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_lookuppoints/query/groupsA 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:

ValueMeans
nameThe collection name in the workspace the URL names
workspace/nameThe 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

MethodPathPurpose
POST{ws}/collections/{name}/points/payloadSet payload — merge
PUT{ws}/collections/{name}/points/payloadOverwrite payload — replace
POST{ws}/collections/{name}/points/payload/deleteDelete named payload keys
PUT{ws}/collections/{name}/indexCreate 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 deployThat agent’s idThe deployment that wrote it; for a task agent, the run
An API key you created yourselfnullnull
The Aetherfy dashboard’s vector explorernullnull

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 testsWhat Aetherfy does
A key the write changes, such as status in a delete of status, or the vector a vector delete removesRecords the author first, then makes your change
__aetherfy_agent_id or __aetherfy_deployment_idMakes your change first, then records the author
NeitherMakes your change, then records the author
BothRefuses 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:

MethodPathPurpose
GET{ws}/collections/{name}/schemaRead the stored payload schema
PUT{ws}/collections/{name}/schemaWrite it. Body: {schema, enforcement_mode?, description?}
DELETE{ws}/collections/{name}/schemaRemove it
POST{ws}/collections/{name}/schema/analyzeInfer 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:

  1. Build the new collection beside the old one. Create articles-v2 and fill it; articles-live keeps serving articles-v1 the 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"}}'
  2. Swap the alias in one batch. create_alias on an existing alias repoints it, and the whole batch applies or none of it does, so there is no moment when articles-live points 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"}}]}'
  3. Delete articles-v1 when 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

MethodPathPurpose
POST{ws}/aliasesApply a batch of alias changes. Body: {"actions": [...]}
GET{ws}/aliasesList the workspace’s aliases, ordered by name
GET{ws}/collections/{name}/aliasesList 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:

ActionFieldsEffect
create_aliasalias_name, collection_namePoint the alias at the collection. An alias that already exists is repointed
delete_aliasalias_nameRemove the alias. The collection is untouched
rename_aliasold_alias_name, new_alias_nameGive 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"
RefusalHTTPWhen
INVALID_REQUEST400No actions, or an empty list
VALIDATION_ERROR400An action that is not an object, of an unknown kind, or with a name that is not a string
CROSS_SCOPE_ALIAS_NOT_ALLOWED400A name with a /: an alias and its collection always share a workspace
INVALID_ALIAS_NAME400The alias name breaks the name rule or begins user_
COLLECTION_NOT_FOUND404The target collection does not exist in this workspace, or is itself an alias
ALIAS_NOT_FOUND404A delete or rename of an alias that does not exist
ALIAS_NAME_IS_A_COLLECTION409The alias would take the name of a collection in this workspace
ALIAS_NAME_TAKEN409A 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 aliasAnswer
Points, index, streaming upsert, a body referenceServed on the collection the alias points at, as if you had named it
Delete or PATCH the collection; write or delete its schema409 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 analyze404 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
cosineCosine
euclidEuclid
dotDot
manhattanManhattan

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.

RequestResultUse instead
Any collection, alias or schema path with no workspace in front400 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 routePOST {ws}/collections
PATCH {ws}/collections/{name} with optimizers_config, hnsw_config, or any key other than name and description400 VALIDATION_ERROROnly the name and description change
POST {ws}/collections/{name}/points expecting upsertNot upsert — falls through to Qdrant’s batch retrieve, which expects body.idsPUT {ws}/collections/{name}/points
POST {ws}/collections/{name}/points/batch (Qdrant’s batch update)405 METHOD_NOT_ALLOWED, nothing appliedOne 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}/index405 METHOD_NOT_ALLOWEDPUT {ws}/collections/{name}/index
Qdrant’s alias routes404: aliases are Aetherfy records, and the engine holds nonePOST {ws}/aliases
Snapshot endpoints404 “Unsupported endpoint”—
/telemetry, /metrics404 “Unsupported endpoint”—
/cluster, /locks, shard endpoints404 “Unsupported endpoint”—
Collection creation with engine tuning fieldsNot accepted — configuration is fixed server-side by Aetherfy—
A payload key beginning __aetherfy_, other than __aetherfy_agent_id and __aetherfy_deployment_id400 RESERVED_FIELD on write; stripped from readsChoose another key
A payload key __aetherfy_agent_id or __aetherfy_deployment_idAccepted and ignored — Aetherfy stamps the attested author and deployment from your credential; returned on readsNothing; 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.

Last updated on