> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veclabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Recall REST API and SDKs.

## Base URL

```
https://api.veclabs.xyz/api/v1
```

All requests require an `Authorization: Bearer YOUR_API_KEY` header.

***

## Collections

### Create a collection

```http theme={null}
POST /collections
```

```json theme={null}
{
  "name": "agent-memory",
  "dimensions": 1536,
  "metric": "cosine"
}
```

**Metrics:** `cosine` (default), `euclidean`, `dot`

**Response:**

```json theme={null}
{
  "collection": {
    "id": "uuid",
    "name": "agent-memory",
    "dimensions": 1536,
    "metric": "cosine",
    "vector_count": 0,
    "created_at": "2026-04-30T00:00:00Z"
  }
}
```

### List collections

```http theme={null}
GET /collections
```

### Delete a collection

```http theme={null}
DELETE /collections/{name}
```

***

## Vectors

### Upsert

```http theme={null}
POST /collections/{name}/upsert
```

```json theme={null}
{
  "records": [
    {
      "id": "mem_001",
      "values": [0.1, 0.2, ...],
      "metadata": { "text": "User prefers dark mode" }
    }
  ]
}
```

**Response:**

```json theme={null}
{
  "upsertedCount": 1,
  "merkleRoot": "90d483c77c4e...",
  "solanaProgram": "8xjQ2XrdhR4JkGAdTEB7i34DBkbrLRkcgchKjN1Vn5nP",
  "solanaTx": "42sxn4j...",
  "solanaExplorerUrl": "https://explorer.solana.com/tx/42sxn4j...?cluster=devnet"
}
```

`solanaTx` and `solanaExplorerUrl` are `null` on the Free tier.

### Query

```http theme={null}
POST /collections/{name}/query
```

```json theme={null}
{
  "vector": [0.1, 0.2, ...],
  "topK": 10,
  "includeValues": false,
  "filter": {}
}
```

**Response:**

```json theme={null}
{
  "matches": [
    {
      "id": "mem_001",
      "score": 0.97,
      "metadata": { "text": "User prefers dark mode" }
    }
  ]
}
```

### Delete vectors

```http theme={null}
POST /collections/{name}/delete
```

```json theme={null}
{
  "ids": ["mem_001", "mem_002"]
}
```

### Fetch vectors by ID

```http theme={null}
POST /collections/{name}/fetch
```

```json theme={null}
{
  "ids": ["mem_001"]
}
```

### Verify collection integrity

```http theme={null}
GET /collections/{name}/verify
```

Fetches the on-chain Merkle root from Solana and computes it locally. Returns a match/mismatch result with a Solana Explorer URL.

**Response:**

```json theme={null}
{
  "verified": true,
  "onChainRoot": "90d483c...",
  "computedRoot": "90d483c...",
  "match": true,
  "vectorCount": 42,
  "solanaExplorerUrl": "https://explorer.solana.com/address/...?cluster=devnet"
}
```

***

## Usage

```http theme={null}
GET /usage
```

Returns current month write, query, and vector counts against your plan limits.

***

## API Keys

### List keys

```http theme={null}
GET /keys
```

### Create a key

```http theme={null}
POST /keys
```

```json theme={null}
{ "name": "Production" }
```

### Revoke a key

```http theme={null}
DELETE /keys/{id}
```

***

## Error codes

| Code | Meaning                                                 |
| ---- | ------------------------------------------------------- |
| 401  | Invalid or missing API key                              |
| 404  | Collection not found                                    |
| 429  | Plan limit reached — upgrade at app.veclabs.xyz/pricing |
| 500  | Internal error — check status.veclabs.xyz               |