# blink / by FractionML (/ ml) — Complete Self-Contained API Reference (`llms-full.txt`)

This document is designed for both human engineers and autonomous coding agents. Every API section below is **100% self-contained** with its full URL, authentication headers, request schema, response schema, and copy-pasteable runnable code.

- **Base URL:** `https://api.fractionml.com`
- **Status URL:** `https://status.fractionml.com/status.json`
- **OpenAPI Spec:** `https://docs.fractionml.com/openapi.json`
- **Authentication:** Include `Authorization: Bearer <BLINK_API_KEY>`, `Authorization: Token <BLINK_API_KEY>`, or `X-API-Key: <BLINK_API_KEY>` on every request. `tenant_id` is derived cryptographically from your API key hash and never passed in payloads.

---

## API 1: Ingest Documents & Code (`POST /v1/blink/ingest`)

- **Endpoint:** `POST https://api.fractionml.com/v1/blink/ingest`
- **Auth Header:** `Authorization: Bearer $BLINK_API_KEY`
- **Content-Type:** `application/json`
- **Purpose:** Ingests 1 to 1,000 documents or code snippets into your isolated tenant vault in a single pass (<10 ms).

### Request Body Schema
| Field | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `documents` | `array<object>` | Yes | — | List of documents to ingest (1–1,000 items). |
| `documents[].id` | `string` | Yes | — | Unique document or chunk identifier within your tenant vault. |
| `documents[].text` | `string` | Yes | — | Raw text, markdown, or source code snippet to index. |
| `documents[].metadata` | `object` | No | `{}` | Arbitrary JSON key-value metadata for filtering during queries. |

### Response Schema (`200 OK`)
| Field | Type | Description |
| :--- | :--- | :--- |
| `status` | `string` | `"ok"` |
| `tenant_id` | `string` | Authenticated tenant identifier resolved from your API key. |
| `ingested_count` | `integer` | Number of documents ingested. |
| `tokens_processed` | `integer` | Total token count processed. |
| `latency_ms` | `number` | Server-side ingestion latency in milliseconds. |

### Self-Contained Runnable Examples
```bash
curl -sS -X POST "https://api.fractionml.com/v1/blink/ingest" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "id": "doc-payment-retry",
        "text": "Idempotency keys expire after 24 hours on POST /v1/charges.",
        "metadata": {"module": "billing", "env": "prod"}
      }
    ]
  }'
```

```python
import httpx, os

resp = httpx.post(
    "https://api.fractionml.com/v1/blink/ingest",
    headers={"Authorization": f"Bearer {os.environ['BLINK_API_KEY']}"},
    json={
        "documents": [
            {
                "id": "doc-payment-retry",
                "text": "Idempotency keys expire after 24 hours on POST /v1/charges.",
                "metadata": {"module": "billing", "env": "prod"},
            }
        ],
    },
    timeout=10.0,
)
resp.raise_for_status()
print(resp.json())
```

---

## API 2: Query Semantic & Symbolic Memory (`POST /v1/blink/query`)

- **Endpoint:** `POST https://api.fractionml.com/v1/blink/query`
- **Auth Header:** `Authorization: Bearer $BLINK_API_KEY`
- **Content-Type:** `application/json`
- **Purpose:** Sub-10ms hybrid semantic and symbolic search across your tenant's ingested documents.

### Request Body Schema
| Field | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `query` | `string` | Yes | — | Natural-language question, symbol name, or code query. |
| `top_k` | `integer` | No | `5` | Maximum number of ranked results to return (1–100). |
| `metadata_filter` | `object` | No | `null` | Optional key-value filter matching `documents[].metadata`. |

### Response Schema (`200 OK`)
| Field | Type | Description |
| :--- | :--- | :--- |
| `results` | `array<object>` | Ranked list of matching memory chunks. |
| `results[].chunk_id` | `string` | Document ID (`id` provided at ingest). |
| `results[].text` | `string` | Stored document text. |
| `results[].score` | `number` | Relevance score (`0.0` to `1.0`). |
| `results[].metadata` | `object` | Document metadata object. |
| `tenant_id` | `string` | Authenticated tenant ID. |
| `latency_ms` | `number` | End-to-end engine evaluation time in milliseconds. |

### Self-Contained Runnable Examples
```bash
curl -sS -X POST "https://api.fractionml.com/v1/blink/query" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "When do idempotency keys expire on charges?",
    "top_k": 3,
    "metadata_filter": {"module": "billing"}
  }'
```

```python
import httpx, os

resp = httpx.post(
    "https://api.fractionml.com/v1/blink/query",
    headers={"Authorization": f"Bearer {os.environ['BLINK_API_KEY']}"},
    json={
        "query": "When do idempotency keys expire on charges?",
        "top_k": 3,
        "metadata_filter": {"module": "billing"},
    },
    timeout=10.0,
)
resp.raise_for_status()
for hit in resp.json()["results"]:
    print(hit["chunk_id"], hit["score"], hit["text"])
```

---

## API 3: Deterministic Forget & GDPR Unlearning (`DELETE /v1/blink/forget`)

- **Endpoint:** `DELETE https://api.fractionml.com/v1/blink/forget`
- **Auth Header:** `Authorization: Bearer $BLINK_API_KEY`
- **Content-Type:** `application/json`
- **Purpose:** Physically purges specified document IDs from the tenant's memory vault and index with zero residual leakage.

### Request Body Schema
| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `document_ids` | `array<string>` | Yes | List of document IDs to permanently purge. |

### Response Schema (`200 OK`)
| Field | Type | Description |
| :--- | :--- | :--- |
| `status` | `string` | `"ok"` |
| `deleted_count` | `integer` | Number of documents physically removed. |
| `gdpr_unlearned` | `boolean` | `true` confirming immediate state removal. |

### Self-Contained Runnable Examples
```bash
curl -sS -X DELETE "https://api.fractionml.com/v1/blink/forget" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"document_ids": ["doc-payment-retry"]}'
```

```python
import httpx, os

resp = httpx.request(
    "DELETE",
    "https://api.fractionml.com/v1/blink/forget",
    headers={"Authorization": f"Bearer {os.environ['BLINK_API_KEY']}"},
    json={"document_ids": ["doc-payment-retry"]},
    timeout=10.0,
)
resp.raise_for_status()
print(resp.json())
```

---

## API 4: Mem0 Add Memories (`POST /v1/memories/`)

- **Endpoint:** `POST https://api.fractionml.com/v1/memories/`
- **Auth Header:** `Authorization: Token $BLINK_API_KEY` (or `Bearer $BLINK_API_KEY`)
- **Content-Type:** `application/json`
- **Purpose:** 1:1 Mem0-compatible memory ingestion from conversational `messages` or direct `text`, scoped to any combination of `user_id`, `agent_id`, `app_id`, `run_id`, `org_id`, and `project_id`.

### Request Body Schema
| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `messages` | `array<{role, content}>` | Cond. | Conversation messages (`[{"role": "user", "content": "..."}]`). Either `messages` or `text` is required. |
| `text` | `string` | Cond. | Direct memory text if `messages` is omitted. |
| `user_id` | `string` | No* | End-user scope identifier (*at least one entity scope `user_id`, `agent_id`, `app_id`, or `run_id` is required). |
| `agent_id` | `string` | No* | Autonomous agent identifier. |
| `app_id` | `string` | No* | Application identifier. |
| `run_id` | `string` | No* | Conversation or workflow run identifier. |
| `org_id` | `string` | No | Organization scope identifier. |
| `project_id` | `string` | No | Project scope identifier. |
| `metadata` | `object` | No | Custom key-value metadata attached to the extracted memories. |
| `immutable` | `boolean` | No | If `true`, prevents subsequent `PUT` updates to this memory. |
| `expiration_date` | `string` | No | ISO-8601 date (`YYYY-MM-DD`) after which the memory expires. |

### Response Schema (`200 OK`)
| Field | Type | Description |
| :--- | :--- | :--- |
| `results` | `array<object>` | Created/updated memory events (`id`, `memory`, `data.memory`, `event`, `event_id`, `user_id`, `agent_id`). |

### Self-Contained Runnable Examples
```bash
curl -sS -X POST "https://api.fractionml.com/v1/memories/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Deployments to prod require two approvals and green E2E tests."}
    ],
    "user_id": "alice",
    "agent_id": "release-bot",
    "metadata": {"team": "platform", "priority": 1}
  }'
```

```python
from mem0 import MemoryClient
import os

client = MemoryClient(
    api_key=os.environ["BLINK_API_KEY"],
    host="https://api.fractionml.com",
)
res = client.add(
    messages=[{"role": "user", "content": "Deployments to prod require two approvals and green E2E tests."}],
    user_id="alice",
    agent_id="release-bot",
    metadata={"team": "platform", "priority": 1},
)
print(res)
```

---

## API 5: Mem0 Search Memories v2 with Boolean Filter DSL (`POST /v2/memories/search/`)

- **Endpoint:** `POST https://api.fractionml.com/v2/memories/search/`
- **Auth Header:** `Authorization: Token $BLINK_API_KEY` (or `Bearer $BLINK_API_KEY`)
- **Content-Type:** `application/json`
- **Purpose:** Searches memories using semantic & symbolic ranking combined with recursive Boolean filter trees (`AND`, `OR`, `NOT`, comparison operators `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `icontains`, and wildcard `"*"`).

### Request Body Schema
| Field | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `query` | `string` | Yes | — | Search query string. |
| `filters` | `object` | No | `{}` | Boolean filter tree over `user_id`, `agent_id`, `app_id`, `run_id`, `org_id`, `project_id`, `categories`, or any `metadata` key. |
| `top_k` / `limit` | `integer` | No | `10` | Maximum memories to return. |
| `threshold` | `number` | No | `0.0` | Minimum relevance score threshold (`0.0`–`1.0`). |
| `rerank` | `boolean` | No | `true` | Apply neural reranking on candidate set. |

### Self-Contained Runnable Examples
```bash
curl -sS -X POST "https://api.fractionml.com/v2/memories/search/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the requirements for prod deployments?",
    "top_k": 5,
    "filters": {
      "AND": [
        {"user_id": "alice"},
        {"agent_id": "*"},
        {"OR": [
          {"team": "platform"},
          {"priority": {"gte": 1}}
        ]}
      ]
    }
  }'
```

```python
import httpx, os

resp = httpx.post(
    "https://api.fractionml.com/v2/memories/search/",
    headers={"Authorization": f"Token {os.environ['BLINK_API_KEY']}"},
    json={
        "query": "What are the requirements for prod deployments?",
        "top_k": 5,
        "filters": {
            "AND": [
                {"user_id": "alice"},
                {"agent_id": "*"},
            ]
        },
    },
    timeout=10.0,
)
resp.raise_for_status()
print(resp.json())
```

---

## API 6: Get, Update, History & Delete Memory by ID (`/v1/memories/{memory_id}/`)

- **Endpoints:**
  - `GET https://api.fractionml.com/v1/memories/{memory_id}/` — Fetch a single memory object.
  - `PUT https://api.fractionml.com/v1/memories/{memory_id}/` — Update `text` and/or `metadata` and record an audit revision.
  - `GET https://api.fractionml.com/v1/memories/{memory_id}/history/` — Retrieve full revision log (`prev_value`, `new_value`, `event`, `timestamp`).
  - `DELETE https://api.fractionml.com/v1/memories/{memory_id}/` — Permanently delete a single memory.

### Self-Contained Runnable Examples
```bash
# 1. Get Memory
curl -sS "https://api.fractionml.com/v1/memories/MEM_ID/" \
  -H "Authorization: Token $BLINK_API_KEY"

# 2. Update Memory
curl -sS -X PUT "https://api.fractionml.com/v1/memories/MEM_ID/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Deployments to prod require two approvals, green E2E tests, and canary verification."}'

# 3. Get Revision History
curl -sS "https://api.fractionml.com/v1/memories/MEM_ID/history/" \
  -H "Authorization: Token $BLINK_API_KEY"

# 4. Delete Memory
curl -sS -X DELETE "https://api.fractionml.com/v1/memories/MEM_ID/" \
  -H "Authorization: Token $BLINK_API_KEY"
```

---

## API 7: Batch Update & Batch Delete Memories (`PUT /v1/batch/` & `DELETE /v1/batch/`)

- **Endpoints:**
  - `PUT https://api.fractionml.com/v1/batch/` — Update up to 1,000 memories atomically.
  - `DELETE https://api.fractionml.com/v1/batch/` — Delete up to 1,000 memories atomically.

### Self-Contained Runnable Examples
```bash
# Batch Update
curl -sS -X PUT "https://api.fractionml.com/v1/batch/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {"memory_id": "MEM_ID_1", "text": "Updated fact 1", "metadata": {"verified": true}},
      {"memory_id": "MEM_ID_2", "text": "Updated fact 2"}
    ]
  }'

# Batch Delete
curl -sS -X DELETE "https://api.fractionml.com/v1/batch/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_ids": ["MEM_ID_1", "MEM_ID_2"]
  }'
```

---

## API 8: Organizations & Projects Control Plane (`/api/v1/orgs/organizations/`)

- **Endpoints:**
  - `POST https://api.fractionml.com/api/v1/orgs/organizations/` — Create Organization (`{"name": "...", "description": "..."}`)
  - `GET https://api.fractionml.com/api/v1/orgs/organizations/` — List Organizations
  - `POST https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/projects/` — Create Project (`{"name": "...", "custom_instructions": "...", "custom_categories": [...]}`)
  - `PATCH https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/projects/{project_id}/` — Update Project instructions/categories
  - `DELETE https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/projects/{project_id}/` — Delete Project

### Self-Contained Runnable Example
```bash
# Create Organization
curl -sS -X POST "https://api.fractionml.com/api/v1/orgs/organizations/" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Engineering", "description": "Core R&D Organization"}'

# Create Project under Organization
curl -sS -X POST "https://api.fractionml.com/api/v1/orgs/organizations/ORG_ID/projects/" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "custom_instructions": "Extract API contracts, SLA limits, and database invariants."
  }'
```

---

## API 9: Entities, Webhooks, Events, Exports, Feedback & Consolidation

### 9A. Entities Directory & Cascade Delete (`/v1/entities/`)
```bash
# List all active users, agents, apps, and runs
curl -sS "https://api.fractionml.com/v1/entities/" \
  -H "Authorization: Bearer $BLINK_API_KEY"

# Cascade-delete an entity and all of its memories
curl -sS -X DELETE "https://api.fractionml.com/v1/entities/user/alice/" \
  -H "Authorization: Bearer $BLINK_API_KEY"
```

### 9B. Project Webhooks (`/api/v1/webhooks/projects/{project_id}/`)
```bash
curl -sS -X POST "https://api.fractionml.com/api/v1/webhooks/projects/PROJECT_ID/" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Audit Webhook",
    "url": "https://example.com/webhooks/blink",
    "eventTypes": ["memory_added", "memory_updated", "memory_deleted"]
  }'
```

### 9C. Event Status Lookup (`GET /v1/event/{event_id}/`)
```bash
curl -sS "https://api.fractionml.com/v1/event/EVENT_ID/" \
  -H "Authorization: Bearer $BLINK_API_KEY"
```

### 9D. Structured Memory Exports (`POST /v1/exports/` & `POST /v1/exports/get`)
```bash
# Create export job
curl -sS -X POST "https://api.fractionml.com/v1/exports/" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"user_id": "alice"}, "schema": {"type": "object"}}'

# Retrieve export payload
curl -sS -X POST "https://api.fractionml.com/v1/exports/get" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"user_id": "alice"}}'
```

### 9E. Memory Feedback & Consolidation (`POST /v1/feedback/` & `POST /v1/memories/consolidate/`)
```bash
# Submit relevance feedback
curl -sS -X POST "https://api.fractionml.com/v1/feedback/" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"memory_id": "MEM_ID", "feedback": "POSITIVE", "feedback_reason": "Exact architectural match"}'

# Consolidate & deduplicate memories for a scope
curl -sS -X POST "https://api.fractionml.com/v1/memories/consolidate/" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "alice"}'
```