# Swift SDK reference

Package layout and configuration for the SurrealDB Agent Memory Swift client.

> [!NOTE]
> `Spectron` was the project name for SurrealDB Agent Memory. These type names
> will be renamed in a future release.

| Item | Value |
| --- | --- |
| Package | `surrealdb.swift` |
| Product | `Spectron` |
| Install | `.product(name: "Spectron", package: "surrealdb.swift")` |
| Import | `import Spectron` |

## Configuration

```swift
let memory = try Spectron(
    context: "acme-prod",
    endpoint: "https://api.spectron.example",
    apiKey: "sk-spec-..."
)
```

| Setting | Purpose |
| --- | --- |
| `context` | Path segment after `/api/v1/` |
| `endpoint` | Base URL (no trailing slash) |
| `apiKey` | Context API key |

## Auth header

```http
Authorization: Bearer <key>
```

## Core operations (REST mapping)

| SDK area | HTTP |
| --- | --- |
| Facts | `POST /api/v1/{ctx}/facts`, `POST .../facts/batch` |
| Query / context | `POST .../query`, `POST .../context` |
| Chat | `POST .../chat` |
| Documents | `POST/GET/DELETE .../documents` |
| Sessions | `POST/GET/DELETE .../sessions` |
| Entities | `GET/DELETE .../entities/{type}/{name}` |
| Governance | `.../scopes`, `.../principals`, `.../keys` |

Full tables: [REST API](/docs/agent-memory/reference/rest-api.md).

## Delegation and idempotency

- Pass `onBehalfOf:` to act as another principal. It is sent as the `X-Spectron-On-Behalf-Of` header.
- Writes carry an `Idempotency-Key` header for safe retry deduplication.

## Errors

All failures throw `SpectronError` with fields `status`, `title`, `detail`, `retryAfter`, `typeURI`, `instance` and `extensions`. The `kind` maps to `.base`, `.auth`, `.scope`, `.notFound`, `.validation`, `.rateLimit` or `.server`. See [Errors](/docs/agent-memory/reference/errors.md).

## User guide

See [Swift SDK](/docs/agent-memory/integrations/sdks/swift.md) for usage patterns.