Aetherfy SDK examples

Worked, end-to-end examples for the Aetherfy vector database and the Aetherfy memory API. Every page is complete: it installs the SDK, reads the API key, constructs a client, performs the task, and shows the shape of what comes back.

Every example is given twice — once in Python and once in JavaScript/TypeScript — under separate headings. The two SDKs are separate implementations with different conventions (Python is synchronous, JS is fully asynchronous), so never translate one into the other by guessing. Use the language section you actually need.

Pages in the Aetherfy cookbook

Installing the Aetherfy SDKs

There is one Python distribution and one npm package. Both are named aetherfy-vectors. There is no scoped @aetherfy/… package on npm.

The single Python distribution aetherfy-vectors ships two import packages: aetherfy_vectors (the vector database client) and aetherfy_memory (the memory layer). You do not install anything extra to get the memory API.

The npm package declares only one export path, ".". Import everything — including the memory client — from the package root. A subpath such as aetherfy-vectors/memory does not resolve.

# Python
pip install aetherfy-vectors

# JavaScript / TypeScript
npm install aetherfy-vectors

Authenticating with an Aetherfy API key

An Aetherfy API key looks like afy_live_… (production) or afy_test_… (test). Create one at https://app.aetherfy.com/dashboard/settings/api-keys .

Both SDKs read the key from the environment when you do not pass one explicitly. They check AETHERFY_API_KEY first, then fall back to AETHERFY_VECTORS_API_KEY.

export AETHERFY_API_KEY="afy_live_your_key_here"

Every example on this site assumes that variable is set and constructs its client with no arguments. Pass api_key= / apiKey: explicitly only when you are managing several keys in one process.

Inside an Aetherfy agent you do not set this at all — the agent machine receives AETHERFY_API_KEY automatically. See An agent that uses memory.

Constructing an Aetherfy client

Python

from aetherfy_vectors import AetherfyVectorsClient
 
# Reads AETHERFY_API_KEY from the environment.
client = AetherfyVectorsClient()
 
# Or configure explicitly. timeout is in SECONDS.
client = AetherfyVectorsClient(
    api_key="afy_live_your_key_here",
    endpoint="https://vectors.aetherfy.com",
    timeout=30.0,
)
 
# The Python client is synchronous and supports the context-manager protocol.
with AetherfyVectorsClient() as client:
    print(client.collection_exists("products"))
 
# Without `with`, close it yourself.
client = AetherfyVectorsClient()
try:
    print(client.collection_exists("products"))
finally:
    client.close()

There is no asynchronous Python client for Aetherfy. Every Python method on this site blocks.

JavaScript / TypeScript

import { AetherfyVectorsClient } from 'aetherfy-vectors';
 
// Reads AETHERFY_API_KEY from the environment.
const client = new AetherfyVectorsClient();
 
// Or configure explicitly. timeout is in MILLISECONDS (default 30000).
const configured = new AetherfyVectorsClient({
  apiKey: 'afy_live_your_key_here',
  endpoint: 'https://vectors.aetherfy.com',
  timeout: 30000,
});
 
async function main() {
  console.log(await client.collectionExists('products'));
  console.log(await client.testConnection());
  client.dispose();
}
 
main();

Every method on the Aetherfy JS client returns a Promise. The client exposes dispose() and destroy() for teardown; there is no context-manager equivalent, so call one of them when your process is done.

testConnection() exists only in the JS SDK. The Python SDK has no equivalent.

The Aetherfy client constructor options

apiRegion in JavaScript requires the async factory. Constructing new AetherfyVectorsClient({ apiRegion: '…' }) throws, because region discovery needs an awaited round trip. Use the static factory instead:

import { AetherfyVectorsClient } from 'aetherfy-vectors';
 
const client = await AetherfyVectorsClient.create({ apiRegion: 'us-east-1' });

Python has no such restriction — AetherfyVectorsClient(api_region="us-east-1") is fine because the client is synchronous.

How Aetherfy plans affect region behaviour

Region placement is plan-scoped. The Free and Starter plans are single-region: your collections live in one region. Multi-region replication begins at the plan named Performance. The regions argument on create_collection / createCollection is only meaningful on a plan that supports more than one region.

Do not assume a collection is replicated unless your plan places it in more than one region. See Regions & replication.

What the Aetherfy SDKs deliberately do not do

These are real gaps, not omissions in the docs. Do not write code that assumes otherwise.

For the full method surface see the SDK reference; for quotas see Limits.