# AIOZ Pin — File Vectors

Base URL: https://api.aiozpin.network/api
Authentication: pinning_api_key + pinning_secret_key headers. The key needs the admin or pin_file_to_ipfs scope.

File Vectors makes pinned UTF-8 text files searchable by meaning. Embedding model: BAAI/bge-m3 (1024 dimensions, more than 100 languages). Long files are split into parts of about 2,000 characters. Query results are pin objects, one per file, best match first.

Supported types: text/*, application/json, application/xml, application/yaml, application/x-yaml, application/javascript, application/typescript, application/csv, and types ending in +json or +xml. PDF, DOCX, images, audio, video, CAR files, and folders return 400. On upload, the type is detected from the content, so most text files are stored as text/plain; charset=utf-8.

## Setup

```typescript
const BASE = 'https://api.aiozpin.network/api'
const PIN_HEADERS = {
  'pinning_api_key': process.env.AIOZ_PIN_API_KEY!,
  'pinning_secret_key': process.env.AIOZ_PIN_SECRET_KEY!
}
```

---

## Vector Status

Pin objects (Get Pin Details, List Pins) have a vectorize_status field:
- not_requested: no vectors were requested (default)
- queued: waiting to run. A file pinned with vectorize: true waits here until it is pinned.
- processing: being read, embedded, and stored
- completed: appears in search results
- failed: the last attempt failed. The API retries in the background, up to 5 attempts in total. After that, call POST /v2/vectorize/files/{cid} to try again. A file with no text always fails.
- deleted: removed from search. Becomes not_requested after cleanup, usually within a day.

---

## Vectorize on Upload

POST https://api.aiozpin.network/api/pinning

Send the options field with vectorize: true. One file only: no folders, no wrap_with_directory, no CAR files.

```typescript
import fs from 'fs'
import path from 'path'

async function pinAndVectorize(filePath: string) {
  const form = new FormData()
  form.append('file', new Blob([await fs.promises.readFile(filePath)]), path.basename(filePath))
  form.append('metadata', JSON.stringify({ name: path.basename(filePath) }))
  form.append('options', JSON.stringify({ vectorize: true }))

  // Do not set Content-Type: fetch adds the multipart boundary itself.
  const res = await fetch(`${BASE}/pinning`, { method: 'POST', headers: PIN_HEADERS, body: form })
  return res.json()
}

const result = await pinAndVectorize('./notes.md')
// result.data.vectorize_status  — 'queued'
// Poll GET /pinning/{pinId} until vectorize_status is 'completed'
```

Errors:
- 400 Unsupported file type for vectorize: <mime type>
- 400 Vectorize only supports a single text file upload
- 400 CAR files are not supported for vectorize
- 409 Pin with that hash already exists (the file is already pinned; use Vectorize a File)

---

## Vectorize on Pin by CID

POST https://api.aiozpin.network/api/pinning/pinByHash

The key needs the pin_by_hash scope. Before pinning, the API reads the file type from the IPFS gateway, which can be slow.

```typescript
async function pinCidAndVectorize(cid: string, name?: string) {
  const res = await fetch(`${BASE}/pinning/pinByHash`, {
    method: 'POST',
    headers: { ...PIN_HEADERS, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      hash_to_pin: cid,
      metadata: name ? { name } : undefined,
      pin_options: { vectorize: true }
    })
  })
  return res.json()
}

const result = await pinCidAndVectorize('Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs', 'notes')
// result.data.vectorize_status  — 'queued' until the CID is pinned
```

Errors:
- 400 Invalid cid
- 400 Unsupported file type for vectorize: <mime type>
- 500 when the gateway cannot return the file (the CID is not pinned)

---

## Vectorize a File

POST https://api.aiozpin.network/api/v2/vectorize/files/{cid}

No body. The request waits until the file is embedded, so a large file can take minutes. Safe to call again: a completed file returns the existing job. Also adds a removed file back to search.

```typescript
async function vectorizeFile(cid: string) {
  const res = await fetch(`${BASE}/v2/vectorize/files/${cid}`, {
    method: 'POST',
    headers: PIN_HEADERS
  })
  return res.json()
}

const result = await vectorizeFile('Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs')
// result.data.status       — 'completed'
// result.data.chunk_count  — number of text parts stored
// result.data.model        — 'BAAI/bge-m3'
```

Response fields:
- id, pin_id, user_id, cid, index_id
- status (always 'completed' on success)
- model, model_version, dimensions, chunk_count, content_hash, attempt_count
- created_at, started_at, completed_at

Errors:
- 400 Invalid cid
- 400 File is not pinned yet
- 400 Unsupported file type for vectorize: <mime type>
- 404 Pin not found
- 500 Something went wrong (vectorize_status becomes failed and is retried in the background)

---

## Query File Vectors

POST https://api.aiozpin.network/api/v2/vectorize/query

```typescript
async function searchFiles(text: string, limit = 10) {
  const res = await fetch(`${BASE}/v2/vectorize/query`, {
    method: 'POST',
    headers: { ...PIN_HEADERS, 'Content-Type': 'application/json' },
    body: JSON.stringify({ text, limit })
  })
  return res.json()
}

const result = await searchFiles('how do I store files on IPFS', 5)
// result.data.query
// result.data.count
// result.data.results[]  — pin objects, best match first
```

Body:
- text (required, cannot be blank)
- limit (default 10, maximum 100; above 100 returns 400 limit must not exceed 100)
- filter (optional; only pin_id works, for example { pin_id: '<pin id>' } to search one file; filters on name or keyvalues return no results)

Notes:
- The response has no similarity score and no matched text. The closest files are returned even when none of them is about the query.
- count can be lower than limit.
- Only files with vectorize_status 'completed' are returned.
- Unpinning a file does not remove it from search. Results can include files with pinned: false until their vectors are removed.

---

## Delete File Vectors

DELETE https://api.aiozpin.network/api/v2/vectorize/files/{cid}

Removes the file from search right away. Does not unpin the file. vectorize_status becomes 'deleted'. Returns 200 even if the file was never vectorized, and 404 if the CID is not in your account.

```typescript
async function removeFromSearch(cid: string) {
  const res = await fetch(`${BASE}/v2/vectorize/files/${cid}`, {
    method: 'DELETE',
    headers: PIN_HEADERS
  })
  return res.json()
}

const result = await removeFromSearch('Qmc1135ziMvmFG534i75E8HpJoLqzLzgKBxfjBV9cBsMAs')
// result.data.message  — 'Vectorize job marked for deletion'
```
