---
slug: examples
title: SDK examples
kind: howto
surface: vectors
summary: Index of the Aetherfy SDK cookbook, with the install line, the AETHERFY_API_KEY setup, and the client construction that every example on this site starts from.
sources:
  - aetherfy-vectors-python-sdk:setup.py
  - aetherfy-vectors-python-sdk:aetherfy_vectors/client.py
  - aetherfy-vectors-js-sdk:package.json
  - aetherfy-vectors-js-sdk:src/client.ts
  - aetherfy-vectors-js-sdk:src/index.ts
---

# 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

| Page | What it shows |
| --- | --- |
| [First collection: upsert & search](/examples/first-collection) | Create an Aetherfy collection, upsert points, run a vector search |
| [Filtered search](/examples/filtered-search) | The `must` / `should` / `must_not` filter vocabulary |
| [Batch upsert & pagination](/examples/batch-and-pagination) | Batched writes and the scroll iterators |
| [Retrieve, delete, count](/examples/retrieve-delete-count) | Fetch by id, delete by id or filter, count points |
| [Collection lifecycle & schema](/examples/collection-lifecycle) | List, exists, get, delete, and the payload schema calls |
| [The memory API](/examples/memory-api) | Namespaces and threads on top of Aetherfy vectors |
| [Bring your own embeddings](/examples/embeddings) | Provider-agnostic wiring — Aetherfy does not embed for you |
| [An agent that uses memory](/examples/agent-with-memory) | An Aetherfy agent that writes and reads memories |

## 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.

| Language | Install | Runtime requirement | Import from |
| --- | --- | --- | --- |
| Python | `pip install aetherfy-vectors` | Python >= 3.9 | `aetherfy_vectors`, `aetherfy_memory` |
| JavaScript / TypeScript | `npm install aetherfy-vectors` | Node >= 20 | `aetherfy-vectors` |

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.

```bash
# Python
pip install aetherfy-vectors
```

```bash
# 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](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`.

```bash
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](/examples/agent-with-memory).

## Constructing an Aetherfy client

### Python

```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

```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

| Option | Python | JavaScript | Notes |
| --- | --- | --- | --- |
| API key | `api_key` | `apiKey` | Falls back to `AETHERFY_API_KEY`, then `AETHERFY_VECTORS_API_KEY` |
| Endpoint | `endpoint` | `endpoint` | Defaults to `https://vectors.aetherfy.com` |
| Timeout | `timeout=30.0` (seconds) | `timeout: 30000` (milliseconds) | Different units — this is the most common porting mistake |
| Workspace | `workspace` | `workspace` | Selects a non-default workspace |
| API region | `api_region` | `apiRegion` | See the warning below |

**`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:

```typescript
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](/platform/regions).

## What the Aetherfy SDKs deliberately do not do

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

| Not supported | What to do instead |
| --- | --- |
| Server-side embedding generation | Aetherfy never turns text into a vector. You compute vectors yourself and pass them in. See [Bring your own embeddings](/examples/embeddings) |
| An async Python client | The Python SDK is synchronous only; run it in a thread if you need concurrency |
| Writing `must_not` in JavaScript | The JS SDK's clause key is `mustNot` and it translates to `must_not`; the snake_case form throws. See [Filtered search](/examples/filtered-search) |
| Arbitrary string point ids | Ids must be an unsigned integer or a UUID string. See [First collection](/examples/first-collection) |

For the full method surface see the [SDK reference](/vectors/sdk); for quotas see [Limits](/platform/limits).