Blink Cloud API Reference

Configuration Item	Production Value	Notes
Base URL	`https://api.fractionml.com`	Global Cloudflare Edge router with strict TLS and low-latency origin peering.
Authentication Header	`Authorization: Bearer $BLINK_API_KEY`	Also accepts `Authorization: Token $BLINK_API_KEY` (Mem0 SDK default).
Content-Type	`application/json`	All request and response bodies are UTF-8 JSON.
Health Check	`GET https://api.fractionml.com/health`	Unauthenticated endpoint returning `{"status":"ok"}`.

Security & Multi-Tenancy

Authentication & Tenant Isolation

All API requests (except GET /health) require an API key in the Authorization header. Your API key is cryptographically bound to your tenant boundary at the edge.

Scope Identifier	Type	How Isolation Works
`org_id`	`string`	Top-level organization partition. Defaults to `"default_org"` if omitted.
`project_id`	`string`	Project-level partition within an organization. Defaults to `"default_project"` if omitted.
`user_id`	`string`	Primary workspace / end-user partition. Memories written under `user_id="alice"` are invisible to `user_id="bob"`.
`agent_id` / `app_id` / `run_id`	`string`	Optional sub-scopes within a project or user namespace for multi-agent workflows and session runs.

Coding Agents

Claude Code, Cursor & Windsurf MCP Setup

Point your MCP client at https://api.fractionml.com to give your coding agent persistent semantic memory and bug localization across sessions.

{
  "mcpServers": {
    "blink-memory": {
      "command": "uvx",
      "args": ["blink-memory", "serve"],
      "env": {
        "BLINK_API_URL": "https://api.fractionml.com",
        "BLINK_API_KEY": "YOUR_BLINK_API_KEY"
      }
    }
  }
}

export BLINK_API_URL="https://api.fractionml.com"
export BLINK_API_KEY="YOUR_BLINK_API_KEY"

Blink Native Engine — Endpoint 1 of 3

Ingest Memory or Code POST `/v1/blink/ingest`

POST https://api.fractionml.com/v1/blink/ingest

Authorization: Bearer $BLINK_API_KEY

Encodes a natural-language memory, architectural decision, or source-code snippet into your isolated GPU VRAM bank and persists the encrypted record to disk. Immediately searchable upon return.

Request Body Schema (`application/json`)

Field	Type	Required	Default	Description
`text`	`string`	REQUIRED	—	Raw text, fact, architectural note, or code snippet to index (1 to 32,000 characters).
`user_id`	`string`	REQUIRED	—	Tenant user or workspace identifier. Isolates the memory in its own GPU VRAM bank.
`project_id`	`string`	OPTIONAL	`"default_project"`	Project namespace identifier.
`org_id`	`string`	OPTIONAL	`"default_org"`	Organization namespace identifier.
`kind`	`string`	OPTIONAL	`"memory"`	Record classification: `"memory"`, `"code"`, `"decision"`, or `"fact"`.
`metadata`	`object`	OPTIONAL	`{}`	Arbitrary JSON key-value metadata (e.g. `{"repo":"payments","file":"src/auth.py"}`) for filtering.

Response Schema (`200 OK`)

Field	Type	Description
`id`	`string`	Unique deterministic identifier for the ingested memory (e.g. `"mem_8f91c2a0"`).
`status`	`string`	Always `"indexed"` when committed to both GPU VRAM and disk.
`user_id`	`string`	Tenant workspace ID that owns this record.
`latency_ms`	`number`	Server-side GPU encoding and indexing latency in milliseconds.

Code Examples

curl -sS -X POST "https://api.fractionml.com/v1/blink/ingest" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Token refresh locks on Redis key auth:refresh: with a 5s TTL to prevent race conditions.",
    "user_id": "workspace_acme",
    "project_id": "proj_backend",
    "kind": "code",
    "metadata": {
      "file": "src/auth/refresh.py",
      "service": "auth-api"
    }
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/v1/blink/ingest",
    headers={
        "Authorization": f"Bearer {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "text": "Token refresh locks on Redis key auth:refresh: with a 5s TTL to prevent race conditions.",
        "user_id": "workspace_acme",
        "project_id": "proj_backend",
        "kind": "code",
        "metadata": {"file": "src/auth/refresh.py", "service": "auth-api"},
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/blink/ingest", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Token refresh locks on Redis key auth:refresh: with a 5s TTL to prevent race conditions.",
    user_id: "workspace_acme",
    project_id: "proj_backend",
    kind: "code",
    metadata: { file: "src/auth/refresh.py", service: "auth-api" },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
console.log(data);

{
  "id": "mem_8f91c2a0",
  "status": "indexed",
  "user_id": "workspace_acme",
  "project_id": "proj_backend",
  "kind": "code",
  "latency_ms": 3.42
}

Blink Native Engine — Endpoint 2 of 3

Query Semantic Memory POST `/v1/blink/query`

POST https://api.fractionml.com/v1/blink/query

Authorization: Bearer $BLINK_API_KEY

Executes a sub-5ms GPU semantic retrieval across your tenant's isolated memory bank, with optional metadata filtering or synthesized answer generation.

Request Body Schema (`application/json`)

Field	Type	Required	Default	Description
`query`	`string`	REQUIRED	—	Natural-language question, bug symptom, or behavioral description.
`user_id`	`string`	REQUIRED	—	Tenant user/workspace ID to search within.
`project_id`	`string`	OPTIONAL	`"default_project"`	Project namespace filter.
`org_id`	`string`	OPTIONAL	`"default_org"`	Organization namespace filter.
`top_k`	`integer`	OPTIONAL	`5`	Maximum number of ranked memories to return (1 to 100).
`mode`	`string`	OPTIONAL	`"retrieve"`	`"retrieve"` returns ranked memory records in ~2.8 ms; `"synthesize"` also generates a grounded answer.
`filters`	`object`	OPTIONAL	`null`	Optional metadata filter dictionary (e.g. `{"service": "auth-api"}`).

Response Schema (`200 OK`)

Field	Type	Description
`results`	`array<object>`	Ranked array of matching memories containing `id`, `text`, `score`, `kind`, `metadata`, and `created_at`.
`answer`	`string \| null`	Synthesized answer when `mode="synthesize"`; `null` when `mode="retrieve"`.
`latency_ms`	`number`	Server-side GPU query execution time in milliseconds.

Code Examples

curl -sS -X POST "https://api.fractionml.com/v1/blink/query" \
  -H "Authorization: Bearer $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do we prevent race conditions during token refresh?",
    "user_id": "workspace_acme",
    "project_id": "proj_backend",
    "top_k": 5,
    "mode": "retrieve"
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/v1/blink/query",
    headers={
        "Authorization": f"Bearer {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "query": "How do we prevent race conditions during token refresh?",
        "user_id": "workspace_acme",
        "project_id": "proj_backend",
        "top_k": 5,
        "mode": "retrieve",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/blink/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "How do we prevent race conditions during token refresh?",
    user_id: "workspace_acme",
    project_id: "proj_backend",
    top_k: 5,
    mode: "retrieve",
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
console.log(data.results);

{
  "results": [
    {
      "id": "mem_8f91c2a0",
      "text": "Token refresh locks on Redis key auth:refresh: with a 5s TTL to prevent race conditions.",
      "score": 0.914,
      "kind": "code",
      "metadata": {
        "file": "src/auth/refresh.py",
        "service": "auth-api"
      },
      "created_at": "2026-10-24T19:30:00Z"
    }
  ],
  "answer": null,
  "latency_ms": 2.74
}

Blink Native Engine — Endpoint 3 of 3

Forget Memory or Tenant Bank DELETE `/v1/blink/forget`

DELETE https://api.fractionml.com/v1/blink/forget

Authorization: Bearer $BLINK_API_KEY

Immediately evicts a single memory (memory_id) or an entire tenant workspace (user_id) from both active GPU VRAM and durable disk storage.

Query Parameters

Parameter	Type	Required	Description
`memory_id`	`string`	ONE REQUIRED	ID of the specific memory to hard-delete (e.g. `mem_8f91c2a0`).
`user_id`	`string`	ONE REQUIRED	If provided without `memory_id`, purges all memories belonging to this `user_id`.

Response Schema (`200 OK`)

Field	Type	Description
`status`	`string`	`"deleted"` once purged from GPU VRAM and disk.
`memory_id`	`string \| null`	ID of the deleted memory record.

Code Examples

curl -sS -X DELETE "https://api.fractionml.com/v1/blink/forget?memory_id=mem_8f91c2a0&user_id=workspace_acme" \
  -H "Authorization: Bearer $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.delete(
    "https://api.fractionml.com/v1/blink/forget",
    headers={"Authorization": f"Bearer {BLINK_API_KEY}"},
    params={"memory_id": "mem_8f91c2a0", "user_id": "workspace_acme"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const params = new URLSearchParams({ memory_id: "mem_8f91c2a0", user_id: "workspace_acme" });

const response = await fetch(`https://api.fractionml.com/v1/blink/forget?${params}`, {
  method: "DELETE",
  headers: { "Authorization": `Bearer ${BLINK_API_KEY}` },
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "status": "deleted",
  "memory_id": "mem_8f91c2a0",
  "user_id": "workspace_acme"
}

Mem0-Compatible API — Create

Add Memories POST `/v1/memories/`

POST https://api.fractionml.com/v1/memories/

Authorization: Token $BLINK_API_KEY

100% wire-compatible with Mem0's client.add(...). Accepts either a list of chat messages or a direct text string, scopes it to your tenant identifiers, and indexes it on GPU.

Request Body Schema (`application/json`)

Field	Type	Required	Default	Description
`messages`	`array<{role, content}>`	ONE OF messages/text	—	Conversation turns (`{"role": "user"\|"assistant", "content": "..."}`) to extract and store.
`text`	`string`	ONE OF messages/text	—	Direct memory text to store if not passing `messages`.
`user_id`	`string`	REQUIRED*	—	End-user or workspace identifier (*at least one of `user_id`, `agent_id`, `app_id`, or `run_id` is required).
`agent_id` / `app_id` / `run_id`	`string`	OPTIONAL	`null`	Optional agent, application, or session run scope identifiers.
`project_id` / `org_id`	`string`	OPTIONAL	`"default_*"`	Optional project and organization partition identifiers.
`metadata`	`object`	OPTIONAL	`{}`	Custom JSON metadata attached to the created memory records.
`categories`	`array<string>`	OPTIONAL	`[]`	Category tags for filtering (e.g. `["architecture", "database"]`).

Response Schema (`200 OK`)

Field	Type	Description
`results`	`array<object>`	Array of created memory event objects with `id`, `memory`, `user_id`, and `event: "ADD"`.

Code Examples

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": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval."},
      {"role": "assistant", "content": "Recorded architecture decision for the storage layer."}
    ],
    "user_id": "alice_dev",
    "agent_id": "coder_v1",
    "metadata": {"team": "platform", "priority": "high"}
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/v1/memories/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "messages": [
            {"role": "user", "content": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval."},
            {"role": "assistant", "content": "Recorded architecture decision for the storage layer."},
        ],
        "user_id": "alice_dev",
        "agent_id": "coder_v1",
        "metadata": {"team": "platform", "priority": "high"},
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/memories/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [
      { role: "user", content: "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval." },
      { role: "assistant", content: "Recorded architecture decision for the storage layer." },
    ],
    user_id: "alice_dev",
    agent_id: "coder_v1",
    metadata: { team: "platform", priority: "high" },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "results": [
    {
      "id": "mem_4d72e901",
      "memory": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval.",
      "user_id": "alice_dev",
      "agent_id": "coder_v1",
      "event": "ADD",
      "created_at": "2026-10-24T19:35:10Z"
    }
  ]
}

Mem0-Compatible API — Search

Search Memories with Filters POST `/v2/memories/search/`

POST https://api.fractionml.com/v2/memories/search/

Authorization: Token $BLINK_API_KEY

Searches memories semantically with full support for Mem0 v2 boolean and comparison filter trees (AND, OR, NOT, in, gte, lte, contains, and wildcard "*"). Also available at POST /v1/memories/search/.

Request Body Schema (`application/json`)

Field	Type	Required	Default	Description
`query`	`string`	REQUIRED	—	Natural-language search query.
`user_id`	`string`	OPTIONAL	`null`	Top-level user scope (can also be passed inside `filters`).
`top_k`	`integer`	OPTIONAL	`10`	Maximum number of memories to return.
`threshold`	`number`	OPTIONAL	`0.0`	Minimum similarity score threshold.
`filters`	`object`	OPTIONAL	`{}`	Structured filter tree supporting `AND`, `OR`, `NOT`, `in`, `gte`, `lte`, `gt`, `lt`, `ne`, `contains`, `icontains`.

Response Schema (`200 OK`)

Field	Type	Description
`results`	`array<object>`	Ranked array of matching memory objects (`id`, `memory`, `score`, `user_id`, `agent_id`, `metadata`, `categories`, `created_at`).

Code Examples

curl -sS -X POST "https://api.fractionml.com/v2/memories/search/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Which database handles storage and semantic retrieval?",
    "user_id": "alice_dev",
    "top_k": 5,
    "filters": {
      "AND": [
        {"user_id": "alice_dev"},
        {"team": {"in": ["platform", "infra"]}}
      ]
    }
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/v2/memories/search/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "query": "Which database handles storage and semantic retrieval?",
        "user_id": "alice_dev",
        "top_k": 5,
        "filters": {
            "AND": [
                {"user_id": "alice_dev"},
                {"team": {"in": ["platform", "infra"]}},
            ]
        },
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v2/memories/search/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Which database handles storage and semantic retrieval?",
    user_id: "alice_dev",
    top_k: 5,
    filters: {
      AND: [
        { user_id: "alice_dev" },
        { team: { in: ["platform", "infra"] } },
      ],
    },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "results": [
    {
      "id": "mem_4d72e901",
      "memory": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval.",
      "score": 0.892,
      "user_id": "alice_dev",
      "agent_id": "coder_v1",
      "metadata": {
        "team": "platform",
        "priority": "high"
      },
      "categories": [],
      "created_at": "2026-10-24T19:35:10Z"
    }
  ]
}

Mem0-Compatible API — List

List Memories GET `/v1/memories/`

GET https://api.fractionml.com/v1/memories/

Authorization: Token $BLINK_API_KEY

Lists all stored memories matching the specified tenant scope with pagination support.

Query Parameters

Parameter	Type	Required	Default	Description
`user_id`	`string`	OPTIONAL	—	Filter memories by user/workspace ID.
`agent_id` / `app_id` / `run_id`	`string`	OPTIONAL	—	Filter memories by agent, app, or session run ID.
`page`	`integer`	OPTIONAL	`1`	1-indexed page number.
`page_size`	`integer`	OPTIONAL	`100`	Number of records per page.

Code Examples

curl -sS -X GET "https://api.fractionml.com/v1/memories/?user_id=alice_dev&page=1&page_size=20" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.get(
    "https://api.fractionml.com/v1/memories/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    params={"user_id": "alice_dev", "page": 1, "page_size": 20},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const params = new URLSearchParams({ user_id: "alice_dev", page: "1", page_size: "20" });

const response = await fetch(`https://api.fractionml.com/v1/memories/?${params}`, {
  method: "GET",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "results": [
    {
      "id": "mem_4d72e901",
      "memory": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval.",
      "user_id": "alice_dev",
      "agent_id": "coder_v1",
      "metadata": {
        "team": "platform",
        "priority": "high"
      },
      "created_at": "2026-10-24T19:35:10Z"
    }
  ]
}

Mem0-Compatible API — Retrieve

Get Single Memory GET `/v1/memories/{memory_id}/`

GET https://api.fractionml.com/v1/memories/{memory_id}/

Authorization: Token $BLINK_API_KEY

Fetches a single memory object by its unique memory_id. Returns 404 Not Found if the memory does not exist or belongs to a different tenant.

Path Parameters

Parameter	Type	Required	Description
`memory_id`	`string`	REQUIRED	Unique identifier of the memory to retrieve (e.g. `mem_4d72e901`).

Code Examples

curl -sS -X GET "https://api.fractionml.com/v1/memories/mem_4d72e901/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]
memory_id = "mem_4d72e901"

response = requests.get(
    f"https://api.fractionml.com/v1/memories/{memory_id}/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const memoryId = "mem_4d72e901";

const response = await fetch(`https://api.fractionml.com/v1/memories/${memoryId}/`, {
  method: "GET",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "id": "mem_4d72e901",
  "memory": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval.",
  "user_id": "alice_dev",
  "agent_id": "coder_v1",
  "metadata": {
    "team": "platform",
    "priority": "high"
  },
  "created_at": "2026-10-24T19:35:10Z",
  "updated_at": "2026-10-24T19:35:10Z"
}

Mem0-Compatible API — Update

Update Memory PUT `/v1/memories/{memory_id}/`

PUT https://api.fractionml.com/v1/memories/{memory_id}/

Authorization: Token $BLINK_API_KEY

Updates a memory's text and/or metadata, re-encodes its GPU representation in place, and appends an UPDATE entry to the memory's audit history.

Request Body Schema (`application/json`)

Field	Type	Required	Description
`text`	`string`	REQUIRED	Updated memory content (also accepts `memory` as an alias).
`metadata`	`object`	OPTIONAL	Updated metadata dictionary.

Code Examples

curl -sS -X PUT "https://api.fractionml.com/v1/memories/mem_4d72e901/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "We standardized on PostgreSQL 16.4 for relational state; Blink Cloud handles all semantic retrieval.",
    "metadata": {"team": "platform", "verified": true}
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]
memory_id = "mem_4d72e901"

response = requests.put(
    f"https://api.fractionml.com/v1/memories/{memory_id}/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "text": "We standardized on PostgreSQL 16.4 for relational state; Blink Cloud handles all semantic retrieval.",
        "metadata": {"team": "platform", "verified": True},
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const memoryId = "mem_4d72e901";

const response = await fetch(`https://api.fractionml.com/v1/memories/${memoryId}/`, {
  method: "PUT",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "We standardized on PostgreSQL 16.4 for relational state; Blink Cloud handles all semantic retrieval.",
    metadata: { team: "platform", verified: true },
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "id": "mem_4d72e901",
  "memory": "We standardized on PostgreSQL 16.4 for relational state; Blink Cloud handles all semantic retrieval.",
  "user_id": "alice_dev",
  "metadata": {
    "team": "platform",
    "verified": true
  },
  "updated_at": "2026-10-24T19:40:00Z"
}

Mem0-Compatible API — Delete

Delete Memory DELETE `/v1/memories/{memory_id}/`

DELETE https://api.fractionml.com/v1/memories/{memory_id}/

Authorization: Token $BLINK_API_KEY

Hard-deletes a single memory by ID from GPU VRAM and disk, and records a DELETE event in the audit log. To delete all memories for a user, call DELETE https://api.fractionml.com/v1/memories/?user_id=alice_dev.

Code Examples

curl -sS -X DELETE "https://api.fractionml.com/v1/memories/mem_4d72e901/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]
memory_id = "mem_4d72e901"

response = requests.delete(
    f"https://api.fractionml.com/v1/memories/{memory_id}/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const memoryId = "mem_4d72e901";

const response = await fetch(`https://api.fractionml.com/v1/memories/${memoryId}/`, {
  method: "DELETE",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

{
  "message": "Memory deleted successfully!"
}

Mem0-Compatible API — Audit Trail

Get Memory History GET `/v1/memories/{memory_id}/history/`

GET https://api.fractionml.com/v1/memories/{memory_id}/history/

Authorization: Token $BLINK_API_KEY

Returns the chronological audit log (ADD, UPDATE, DELETE) for a specific memory, including old_memory and new_memory snapshots.

Code Examples

curl -sS -X GET "https://api.fractionml.com/v1/memories/mem_4d72e901/history/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]
memory_id = "mem_4d72e901"

response = requests.get(
    f"https://api.fractionml.com/v1/memories/{memory_id}/history/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const memoryId = "mem_4d72e901";

const response = await fetch(`https://api.fractionml.com/v1/memories/${memoryId}/history/`, {
  method: "GET",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});

if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());

[
  {
    "id": "hist_01",
    "memory_id": "mem_4d72e901",
    "old_memory": null,
    "new_memory": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval.",
    "event": "ADD",
    "created_at": "2026-10-24T19:35:10Z"
  },
  {
    "id": "hist_02",
    "memory_id": "mem_4d72e901",
    "old_memory": "We standardized on PostgreSQL 16 with pgvector disabled; Blink handles all semantic retrieval.",
    "new_memory": "We standardized on PostgreSQL 16.4 for relational state; Blink Cloud handles all semantic retrieval.",
    "event": "UPDATE",
    "created_at": "2026-10-24T19:40:00Z"
  }
]

Mem0-Compatible API — Batch Operations

Batch Update & Batch Delete PUT DELETE `/v1/batch/`

PUT DELETE https://api.fractionml.com/v1/batch/

Authorization: Token $BLINK_API_KEY

Updates or deletes up to 1,000 memories atomically in a single HTTP call.

Request Body Schema (`application/json`)

Field	Type	Required	Description
`memories`	`array<object>`	REQUIRED	For `PUT`: list of `{"memory_id": "...", "text": "...", "metadata": {...}}`. For `DELETE`: list of `{"memory_id": "..."}`.

Code Examples

# Batch Update Memories
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_4d72e901", "text": "Updated memory 1", "metadata": {"reviewed": true}}
    ]
  }'

# Batch Delete Memories
curl -sS -X DELETE "https://api.fractionml.com/v1/batch/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {"memory_id": "mem_4d72e901"}
    ]
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

# Batch Update
update_res = requests.put(
    "https://api.fractionml.com/v1/batch/",
    headers={"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"},
    json={"memories": [{"memory_id": "mem_4d72e901", "text": "Updated memory 1"}]},
    timeout=10,
)
print(update_res.json())

# Batch Delete
delete_res = requests.delete(
    "https://api.fractionml.com/v1/batch/",
    headers={"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"},
    json={"memories": [{"memory_id": "mem_4d72e901"}]},
    timeout=10,
)
print(delete_res.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

// Batch Update
const updateRes = await fetch("https://api.fractionml.com/v1/batch/", {
  method: "PUT",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    memories: [{ memory_id: "mem_4d72e901", text: "Updated memory 1" }],
  }),
});
console.log(await updateRes.json());

{
  "message": "Successfully updated 1 memories"
}

Platform & Governance

POST Create Organization (`/api/v1/orgs/organizations/`)

POST https://api.fractionml.com/api/v1/orgs/organizations/

Authorization: Token $BLINK_API_KEY

Creates a top-level Organization container for multi-project governance, role-based member management, and billing segmentation.

Request Body (`application/json`)

Field	Type	Required	Description
`name`	`string`	Required	Display name of the organization (e.g. `"Acme Engineering"`).
`description`	`string`	Optional	Human-readable summary of the organization's purpose or team scope.

Code Examples

curl -sS -X POST "https://api.fractionml.com/api/v1/orgs/organizations/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Engineering",
    "description": "Production AI Engineering & Agent Memory"
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/api/v1/orgs/organizations/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Acme Engineering",
        "description": "Production AI Engineering & Agent Memory",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/api/v1/orgs/organizations/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme Engineering",
    description: "Production AI Engineering & Agent Memory",
  }),
});
console.log(await response.json());

{
  "id": "org_7c812a",
  "org_id": "org_7c812a",
  "name": "Acme Engineering",
  "description": "Production AI Engineering & Agent Memory",
  "owner_id": "tenant_root",
  "created_at": "2026-10-24T19:45:00Z",
  "updated_at": "2026-10-24T19:45:00Z"
}

Platform & Governance

GETDELETE List, Get & Delete Organizations (`/api/v1/orgs/organizations/`)

GET DELETE https://api.fractionml.com/api/v1/orgs/organizations/

Authorization: Token $BLINK_API_KEY

List all organizations owned by your tenant, retrieve a single organization by {org_id}, or permanently delete an organization and its nested projects.

Endpoint Variants

Method	Full Endpoint URL	Description
GET	`https://api.fractionml.com/api/v1/orgs/organizations/`	Returns an array of all organizations accessible to the caller's API key.
GET	`https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/`	Returns metadata and timestamps for a specific `org_id`.
DELETE	`https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/`	Deletes the organization and cascades to its projects and members.

Code Examples

# List all organizations
curl -sS -X GET "https://api.fractionml.com/api/v1/orgs/organizations/" \
  -H "Authorization: Token $BLINK_API_KEY"

# Inspect a single organization
curl -sS -X GET "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/" \
  -H "Authorization: Token $BLINK_API_KEY"

# Delete an organization
curl -sS -X DELETE "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.get(
    "https://api.fractionml.com/api/v1/orgs/organizations/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/api/v1/orgs/organizations/", {
  method: "GET",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});
console.log(await response.json());

[
  {
    "id": "org_7c812a",
    "org_id": "org_7c812a",
    "name": "Acme Engineering",
    "description": "Production AI Engineering & Agent Memory",
    "created_at": "2026-10-24T19:45:00Z",
    "updated_at": "2026-10-24T19:45:00Z"
  }
]

Platform & Governance

POSTGET Organization Members (`/api/v1/orgs/organizations/{org_id}/members/`)

POST GET https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/members/

Authorization: Token $BLINK_API_KEY

Invite or register team members inside an organization (`POST`) with a designated governance role (ADMIN, MEMBER, or VIEWER), or list all active members (`GET`).

Request Body for `POST` (`application/json`)

Field	Type	Required	Description
`email`	`string`	Required	Email address of the member to add (e.g. `"alice@acme.com"`).
`role`	`string`	Optional	Governance role: `"ADMIN"`, `"MEMBER"` (default), or `"VIEWER"`.

Code Examples

# Add a member to org_7c812a
curl -sS -X POST "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/members/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@acme.com",
    "role": "ADMIN"
  }'

# List all members of org_7c812a
curl -sS -X GET "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/members/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/members/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={"email": "alice@acme.com", "role": "ADMIN"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/members/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "alice@acme.com", role: "ADMIN" }),
});
console.log(await response.json());

{
  "org_id": "org_7c812a",
  "email": "alice@acme.com",
  "role": "ADMIN",
  "status": "active",
  "added_at": "2026-10-24T19:46:12Z"
}

Platform & Governance

POSTGET Create & List Projects (`/api/v1/orgs/organizations/{org_id}/projects/`)

POST GET https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/projects/

Authorization: Token $BLINK_API_KEY

Creates a new Project inside an Organization (`POST`) or lists all Projects in that Organization (`GET`). Projects allow you to define default custom_instructions and custom_categories that govern memory extraction and classification across all calls scoped to that project_id.

Request Body for `POST` (`application/json`)

Field	Type	Required	Description
`name`	`string`	Required	Project display name (e.g. `"Payments Core"`).
`description`	`string`	Optional	Summary of the project's environment or service boundary.
`custom_instructions`	`string`	Optional	Project-wide memory extraction guidelines applied whenever `project_id` is passed.
`custom_categories`	`array<string>`	Optional	Allowed taxonomy tags for memories stored in this project (e.g. `["architecture", "incident", "security"]`).

Code Examples

# Create a Project with custom extraction rules
curl -sS -X POST "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payments Core",
    "description": "Stripe & Ledger Settlement Services",
    "custom_instructions": "Always preserve idempotency keys, SQL migration invariants, and root-cause incident notes.",
    "custom_categories": ["architecture", "incident", "security", "runbook"]
  }'

# List all Projects in org_7c812a
curl -sS -X GET "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Payments Core",
        "description": "Stripe & Ledger Settlement Services",
        "custom_instructions": "Always preserve idempotency keys, SQL migration invariants, and root-cause incident notes.",
        "custom_categories": ["architecture", "incident", "security", "runbook"],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Payments Core",
    description: "Stripe & Ledger Settlement Services",
    custom_instructions: "Always preserve idempotency keys, SQL migration invariants, and root-cause incident notes.",
    custom_categories: ["architecture", "incident", "security", "runbook"],
  }),
});
console.log(await response.json());

{
  "id": "proj_99b1e4",
  "project_id": "proj_99b1e4",
  "org_id": "org_7c812a",
  "name": "Payments Core",
  "description": "Stripe & Ledger Settlement Services",
  "custom_instructions": "Always preserve idempotency keys, SQL migration invariants, and root-cause incident notes.",
  "custom_categories": ["architecture", "incident", "security", "runbook"],
  "created_at": "2026-10-24T19:48:00Z",
  "updated_at": "2026-10-24T19:48:00Z"
}

Platform & Governance

PATCHGET Update Project Governance (`/api/v1/orgs/organizations/{org_id}/projects/{project_id}/`)

PATCH GET https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/projects/{project_id}/

Authorization: Token $BLINK_API_KEY

Updates a project's custom_instructions, custom_categories, name, or description in place (`PATCH` or `PUT`), or retrieves the current project configuration (`GET`).

Request Body for `PATCH` (`application/json`)

Field	Type	Required	Description
`custom_instructions`	`string`	Optional	Updated instruction prompt governing what facts should be prioritized or ignored.
`custom_categories`	`array<string>`	Optional	Updated list of category tags for automatic memory classification.
`name` / `description`	`string`	Optional	Updated project name or description.

Code Examples

curl -sS -X PATCH "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/proj_99b1e4/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_instructions": "Prioritize PCI-DSS compliance constraints and ledger reconciliation rules.",
    "custom_categories": ["architecture", "incident", "security", "pci_compliance"]
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.patch(
    "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/proj_99b1e4/",
    headers={
        "Authorization": f"Token {BLINK_API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "custom_instructions": "Prioritize PCI-DSS compliance constraints and ledger reconciliation rules.",
        "custom_categories": ["architecture", "incident", "security", "pci_compliance"],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch(
  "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/proj_99b1e4/",
  {
    method: "PATCH",
    headers: {
      "Authorization": `Token ${BLINK_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      custom_instructions: "Prioritize PCI-DSS compliance constraints and ledger reconciliation rules.",
      custom_categories: ["architecture", "incident", "security", "pci_compliance"],
    }),
  }
);
console.log(await response.json());

{
  "id": "proj_99b1e4",
  "project_id": "proj_99b1e4",
  "org_id": "org_7c812a",
  "name": "Payments Core",
  "custom_instructions": "Prioritize PCI-DSS compliance constraints and ledger reconciliation rules.",
  "custom_categories": ["architecture", "incident", "security", "pci_compliance"],
  "updated_at": "2026-10-24T19:50:30Z"
}

Platform & Governance

DELETE Delete Project (`/api/v1/orgs/organizations/{org_id}/projects/{project_id}/`)

DELETE https://api.fractionml.com/api/v1/orgs/organizations/{org_id}/projects/{project_id}/

Authorization: Token $BLINK_API_KEY

Permanently deletes a project definition and its associated project member bindings and webhook registrations. You can also manage project-level members via POST / GET /api/v1/orgs/organizations/{org_id}/projects/{project_id}/members/.

Code Examples

curl -sS -X DELETE "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/proj_99b1e4/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.delete(
    "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/proj_99b1e4/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch(
  "https://api.fractionml.com/api/v1/orgs/organizations/org_7c812a/projects/proj_99b1e4/",
  {
    method: "DELETE",
    headers: { "Authorization": `Token ${BLINK_API_KEY}` },
  }
);
console.log(await response.json());

{
  "message": "Project deleted successfully"
}

Platform & Governance

GET List Entities & Users Directory (`/v1/entities/`)

GET https://api.fractionml.com/v1/entities/

Authorization: Token $BLINK_API_KEY

Lists all active user, agent, app, and run entities inside your tenant namespace along with their live memory counts and timestamps. Also available at the alias GET /v1/users/.

Query Parameters

Parameter	Type	Required	Description
`org_id`	`string`	Optional	Filter entities belonging to a specific organization.
`project_id`	`string`	Optional	Filter entities belonging to a specific project.

Code Examples

curl -sS -X GET "https://api.fractionml.com/v1/entities/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.get(
    "https://api.fractionml.com/v1/entities/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/entities/", {
  method: "GET",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});
console.log(await response.json());

{
  "count": 2,
  "results": [
    {
      "id": "alice_dev",
      "name": "alice_dev",
      "type": "user",
      "total_memories": 14,
      "created_at": "2026-10-24T19:35:10Z",
      "updated_at": "2026-10-24T19:49:02Z"
    },
    {
      "id": "code_reviewer_v2",
      "name": "code_reviewer_v2",
      "type": "agent",
      "total_memories": 6,
      "created_at": "2026-10-24T19:40:00Z",
      "updated_at": "2026-10-24T19:48:11Z"
    }
  ]
}

Platform & Governance

DELETE Cascade-Delete Entity & Memories (`/v1/entities/{entity_type}/{entity_id}/`)

DELETE https://api.fractionml.com/v1/entities/{entity_type}/{entity_id}/

Authorization: Token $BLINK_API_KEY

Executes a GDPR / right-to-be-forgotten cascade wipe for a specific entity (`user`, `agent`, `app`, or `run`), simultaneously unlearning all of its memories from GPU state and purging its metadata rows from disk.

Path Parameters

Parameter	Type	Required	Description
`entity_type`	`string`	Required	One of `user`, `agent`, `app`, or `run`.
`entity_id`	`string`	Required	Target entity identifier (e.g. `alice_dev`).

Code Examples

curl -sS -X DELETE "https://api.fractionml.com/v1/entities/user/alice_dev/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.delete(
    "https://api.fractionml.com/v1/entities/user/alice_dev/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/entities/user/alice_dev/", {
  method: "DELETE",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});
console.log(await response.json());

{
  "message": "Entity user:alice_dev and 14 memories deleted successfully!"
}

Platform & Governance

POSTGET Create & List Project Webhooks (`/api/v1/webhooks/projects/{project_id}/webhooks/`)

POST GET https://api.fractionml.com/api/v1/webhooks/projects/{project_id}/webhooks/

Authorization: Token $BLINK_API_KEY

Registers an outbound webhook URL (`POST`) or lists all registered webhooks (`GET`) for a project. Webhooks receive real-time JSON POST notifications whenever memories are added, updated, or deleted.

Request Body for `POST` (`application/json`)

Field	Type	Required	Description
`name`	`string`	Required	Descriptive name for the webhook sink (e.g. `"SIEM Audit Sink"`).
`url`	`string (URL)`	Required	HTTPS destination URL that will receive POST event payloads.
`event_types`	`array<string>`	Optional	Subscribed events: `["memory_add", "memory_update", "memory_delete"]`.

Code Examples

# Register a webhook on project proj_99b1e4
curl -sS -X POST "https://api.fractionml.com/api/v1/webhooks/projects/proj_99b1e4/webhooks/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Audit SIEM Sink",
    "url": "https://example.com/webhooks/blink",
    "event_types": ["memory_add", "memory_update", "memory_delete"]
  }'

# List all webhooks for project proj_99b1e4
curl -sS -X GET "https://api.fractionml.com/api/v1/webhooks/projects/proj_99b1e4/webhooks/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/api/v1/webhooks/projects/proj_99b1e4/webhooks/",
    headers={"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"},
    json={
        "name": "Audit SIEM Sink",
        "url": "https://example.com/webhooks/blink",
        "event_types": ["memory_add", "memory_update", "memory_delete"],
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/api/v1/webhooks/projects/proj_99b1e4/webhooks/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Audit SIEM Sink",
    url: "https://example.com/webhooks/blink",
    event_types: ["memory_add", "memory_update", "memory_delete"],
  }),
});
console.log(await response.json());

{
  "id": "wh_92b41f",
  "webhook_id": "wh_92b41f",
  "project_id": "proj_99b1e4",
  "name": "Audit SIEM Sink",
  "url": "https://example.com/webhooks/blink",
  "event_types": ["memory_add", "memory_update", "memory_delete"],
  "is_active": true,
  "created_at": "2026-10-24T19:52:00Z"
}

Platform & Governance

PUTDELETE Update & Delete Webhook (`/api/v1/webhooks/webhooks/{webhook_id}/`)

PUT PATCH DELETE https://api.fractionml.com/api/v1/webhooks/webhooks/{webhook_id}/

Authorization: Token $BLINK_API_KEY

Updates an existing webhook's destination url, name, event_types, or is_active flag (`PUT` / `PATCH`), or permanently removes the webhook registration (`DELETE`).

Code Examples

# Update a webhook's subscribed event types
curl -sS -X PUT "https://api.fractionml.com/api/v1/webhooks/webhooks/wh_92b41f/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Audit SIEM Sink (Deletes Only)",
    "url": "https://example.com/webhooks/blink",
    "event_types": ["memory_delete"],
    "is_active": true
  }'

# Delete a webhook
curl -sS -X DELETE "https://api.fractionml.com/api/v1/webhooks/webhooks/wh_92b41f/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

# Update webhook
updated = requests.put(
    "https://api.fractionml.com/api/v1/webhooks/webhooks/wh_92b41f/",
    headers={"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"},
    json={
        "name": "Audit SIEM Sink (Deletes Only)",
        "url": "https://example.com/webhooks/blink",
        "event_types": ["memory_delete"],
        "is_active": True,
    },
    timeout=10,
).json()
print(updated)

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/api/v1/webhooks/webhooks/wh_92b41f/", {
  method: "DELETE",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});
console.log(await response.json());

{
  "id": "wh_92b41f",
  "webhook_id": "wh_92b41f",
  "name": "Audit SIEM Sink (Deletes Only)",
  "url": "https://example.com/webhooks/blink",
  "event_types": ["memory_delete"],
  "is_active": true,
  "updated_at": "2026-10-24T19:53:10Z"
}

Platform & Governance

GET Event Ledger & Operation Status (`/v1/events/` & `/v1/event/{event_id}/`)

GET https://api.fractionml.com/v1/events/

Authorization: Token $BLINK_API_KEY

Queries your tenant's operation ledger (`ADD`, `UPDATE`, `DELETE`, `BATCH_UPDATE`, `CONSOLIDATE`) with latency metrics and status codes (`SUCCEEDED` / `FAILED`). Use GET /v1/events/ to list recent events or GET /v1/event/{event_id}/ to inspect a specific operation.

Code Examples

# List recent events in the tenant ledger
curl -sS -X GET "https://api.fractionml.com/v1/events/" \
  -H "Authorization: Token $BLINK_API_KEY"

# Inspect a specific event by ID
curl -sS -X GET "https://api.fractionml.com/v1/event/evt_83a91c02/" \
  -H "Authorization: Token $BLINK_API_KEY"

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

events = requests.get(
    "https://api.fractionml.com/v1/events/",
    headers={"Authorization": f"Token {BLINK_API_KEY}"},
    timeout=10,
).json()
print(events)

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/events/", {
  method: "GET",
  headers: { "Authorization": `Token ${BLINK_API_KEY}` },
});
console.log(await response.json());

{
  "results": [
    {
      "id": "evt_83a91c02",
      "event_type": "ADD",
      "status": "SUCCEEDED",
      "latency": 2.14,
      "created_at": "2026-10-24T19:35:10Z",
      "updated_at": "2026-10-24T19:35:10Z"
    }
  ]
}

Platform & Governance

POST Portable Memory Exports (`/v1/exports/` & `/v1/exports/get/`)

POST https://api.fractionml.com/v1/exports/

Authorization: Token $BLINK_API_KEY

Generates a structured, portable JSON snapshot of all memories matching your filter criteria (`POST /v1/exports/`) and retrieves the completed snapshot payload (`POST /v1/exports/get/`) for compliance archiving or offline analysis.

Request Body (`application/json`)

Endpoint	Field	Type	Description
`POST /v1/exports/`	`filters`	`object`	Optional filter dictionary (e.g. `{"user_id": "alice_dev"}`) scoping which memories to export.
`POST /v1/exports/`	`schema`	`object`	Optional schema descriptor saved alongside the export artifact.
`POST /v1/exports/get/`	`export_id`	`string`	The `export_id` returned by `POST /v1/exports/` (if omitted, returns the most recent export).

Code Examples

# 1. Create a memory export job
curl -sS -X POST "https://api.fractionml.com/v1/exports/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"user_id": "alice_dev"}}'

# 2. Retrieve the exported memory snapshot
curl -sS -X POST "https://api.fractionml.com/v1/exports/get/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"export_id": "exp_55d019"}'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]
headers = {"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"}

job = requests.post(
    "https://api.fractionml.com/v1/exports/",
    headers=headers,
    json={"filters": {"user_id": "alice_dev"}},
    timeout=10,
).json()

snapshot = requests.post(
    "https://api.fractionml.com/v1/exports/get/",
    headers=headers,
    json={"export_id": job["id"]},
    timeout=10,
).json()
print(snapshot)

const BLINK_API_KEY = process.env.BLINK_API_KEY!;
const headers = {
  "Authorization": `Token ${BLINK_API_KEY}`,
  "Content-Type": "application/json",
};

const jobRes = await fetch("https://api.fractionml.com/v1/exports/", {
  method: "POST",
  headers,
  body: JSON.stringify({ filters: { user_id: "alice_dev" } }),
});
const job = await jobRes.json();

const snapRes = await fetch("https://api.fractionml.com/v1/exports/get/", {
  method: "POST",
  headers,
  body: JSON.stringify({ export_id: job.id }),
});
console.log(await snapRes.json());

{
  "id": "exp_55d019",
  "export_id": "exp_55d019",
  "status": "COMPLETED",
  "created_at": "2026-10-24T19:54:00Z",
  "data": {
    "memories": [
      {
        "id": "mem_4d72e901",
        "memory": "User prefers concise Python 3.12 code using uv and pytest.",
        "user_id": "alice_dev",
        "categories": ["preference"]
      }
    ]
  }
}

Platform & Governance

POST Submit Memory Relevance Feedback (`/v1/feedback/`)

POST https://api.fractionml.com/v1/feedback/

Authorization: Token $BLINK_API_KEY

Records explicit human or agent quality feedback (`POSITIVE`, `NEGATIVE`, or `VERY_NEGATIVE`) on a specific memory_id to track recall utility and flag stale memories for review.

Request Body (`application/json`)

Field	Type	Required	Description
`memory_id`	`string`	Required	Target memory ID being rated (e.g. `"mem_4d72e901"`).
`feedback`	`string`	Optional	Rating signal: `"POSITIVE"`, `"NEGATIVE"`, or `"VERY_NEGATIVE"`.
`feedback_reason`	`string`	Optional	Free-text explanation from the user or evaluating agent.

Code Examples

curl -sS -X POST "https://api.fractionml.com/v1/feedback/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "mem_4d72e901",
    "feedback": "POSITIVE",
    "feedback_reason": "Prevented duplicate database migration bug."
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/v1/feedback/",
    headers={"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"},
    json={
        "memory_id": "mem_4d72e901",
        "feedback": "POSITIVE",
        "feedback_reason": "Prevented duplicate database migration bug.",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/feedback/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    memory_id: "mem_4d72e901",
    feedback: "POSITIVE",
    feedback_reason: "Prevented duplicate database migration bug.",
  }),
});
console.log(await response.json());

{
  "id": "fb_3019ef",
  "memory_id": "mem_4d72e901",
  "feedback": "POSITIVE",
  "feedback_reason": "Prevented duplicate database migration bug.",
  "created_at": "2026-10-24T19:55:12Z"
}

Platform & Governance

POST Consolidate & Deduplicate Memories (`/v1/memories/consolidate/`)

POST https://api.fractionml.com/v1/memories/consolidate/

Authorization: Token $BLINK_API_KEY

Scans a user's or agent's memory bank for near-duplicate facts and consolidates redundant records while keeping GPU state and persistent storage synchronized.

Request Body (`application/json`)

Field	Type	Required	Description
`user_id` / `agent_id`	`string`	Optional	Scope consolidation to a specific user or agent (consolidates across the caller's tenant if omitted).
`similarity_threshold`	`number (float)`	Optional	Similarity threshold in `[0.0, 1.0]` above which memories are merged (default: `0.92`).

Code Examples

curl -sS -X POST "https://api.fractionml.com/v1/memories/consolidate/" \
  -H "Authorization: Token $BLINK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "alice_dev",
    "similarity_threshold": 0.92
  }'

import os
import requests

BLINK_API_KEY = os.environ["BLINK_API_KEY"]

response = requests.post(
    "https://api.fractionml.com/v1/memories/consolidate/",
    headers={"Authorization": f"Token {BLINK_API_KEY}", "Content-Type": "application/json"},
    json={"user_id": "alice_dev", "similarity_threshold": 0.92},
    timeout=15,
)
response.raise_for_status()
print(response.json())

const BLINK_API_KEY = process.env.BLINK_API_KEY!;

const response = await fetch("https://api.fractionml.com/v1/memories/consolidate/", {
  method: "POST",
  headers: {
    "Authorization": `Token ${BLINK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ user_id: "alice_dev", similarity_threshold: 0.92 }),
});
console.log(await response.json());

{
  "user_id": "alice_dev",
  "consolidated_count": 2,
  "remaining_count": 12,
  "status": "completed"
}

Diagnostics

HTTP Status Codes & Error Format

All error responses return a consistent JSON body: {"detail": "Human-readable explanation"}.

Status Code	Meaning	Resolution
`200 OK` / `201 Created`	Success	Request completed and changes are durable on GPU and disk.
`400 Bad Request`	Validation Error	Check required fields (e.g. missing `user_id` or `query`).
`401 Unauthorized`	Missing or Invalid API Key	Include `Authorization: Bearer $BLINK_API_KEY` or `Authorization: Token $BLINK_API_KEY`.
`404 Not Found`	Resource Not Found	The requested `memory_id` does not exist or belongs to a different tenant namespace.
`429 Too Many Requests`	Rate Limit Exceeded	Retry with exponential backoff starting at 250ms.

Blink Cloud API Reference

Authentication & Tenant Isolation

Claude Code, Cursor & Windsurf MCP Setup

Ingest Memory or Code POST /v1/blink/ingest

Request Body Schema (application/json)

Response Schema (200 OK)

Code Examples

Query Semantic Memory POST /v1/blink/query

Request Body Schema (application/json)

Response Schema (200 OK)

Code Examples

Forget Memory or Tenant Bank DELETE /v1/blink/forget

Query Parameters

Response Schema (200 OK)

Code Examples

Add Memories POST /v1/memories/

Request Body Schema (application/json)

Response Schema (200 OK)

Code Examples

Search Memories with Filters POST /v2/memories/search/

Request Body Schema (application/json)

Response Schema (200 OK)

Code Examples

List Memories GET /v1/memories/

Query Parameters

Code Examples

Get Single Memory GET /v1/memories/{memory_id}/

Path Parameters

Code Examples

Update Memory PUT /v1/memories/{memory_id}/

Request Body Schema (application/json)

Code Examples

Delete Memory DELETE /v1/memories/{memory_id}/

Code Examples

Get Memory History GET /v1/memories/{memory_id}/history/

Code Examples

Batch Update & Batch Delete PUT DELETE /v1/batch/

Request Body Schema (application/json)

Code Examples

POST Create Organization (/api/v1/orgs/organizations/)

Request Body (application/json)

Code Examples

GETDELETE List, Get & Delete Organizations (/api/v1/orgs/organizations/)

Endpoint Variants

Code Examples

POSTGET Organization Members (/api/v1/orgs/organizations/{org_id}/members/)

Request Body for POST (application/json)

Code Examples

POSTGET Create & List Projects (/api/v1/orgs/organizations/{org_id}/projects/)

Request Body for POST (application/json)

Code Examples

PATCHGET Update Project Governance (/api/v1/orgs/organizations/{org_id}/projects/{project_id}/)

Request Body for PATCH (application/json)

Code Examples

DELETE Delete Project (/api/v1/orgs/organizations/{org_id}/projects/{project_id}/)

Code Examples

GET List Entities & Users Directory (/v1/entities/)

Query Parameters

Code Examples

DELETE Cascade-Delete Entity & Memories (/v1/entities/{entity_type}/{entity_id}/)

Path Parameters

Code Examples

POSTGET Create & List Project Webhooks (/api/v1/webhooks/projects/{project_id}/webhooks/)

Request Body for POST (application/json)

Code Examples

PUTDELETE Update & Delete Webhook (/api/v1/webhooks/webhooks/{webhook_id}/)

Code Examples

GET Event Ledger & Operation Status (/v1/events/ & /v1/event/{event_id}/)

Code Examples

POST Portable Memory Exports (/v1/exports/ & /v1/exports/get/)

Request Body (application/json)

Code Examples

POST Submit Memory Relevance Feedback (/v1/feedback/)

Request Body (application/json)

Code Examples

POST Consolidate & Deduplicate Memories (/v1/memories/consolidate/)

Request Body (application/json)

Code Examples

HTTP Status Codes & Error Format

Ingest Memory or Code POST `/v1/blink/ingest`

Request Body Schema (`application/json`)

Response Schema (`200 OK`)

Query Semantic Memory POST `/v1/blink/query`

Request Body Schema (`application/json`)

Response Schema (`200 OK`)

Forget Memory or Tenant Bank DELETE `/v1/blink/forget`

Response Schema (`200 OK`)

Add Memories POST `/v1/memories/`

Request Body Schema (`application/json`)

Response Schema (`200 OK`)

Search Memories with Filters POST `/v2/memories/search/`

Request Body Schema (`application/json`)

Response Schema (`200 OK`)

List Memories GET `/v1/memories/`

Get Single Memory GET `/v1/memories/{memory_id}/`

Update Memory PUT `/v1/memories/{memory_id}/`

Request Body Schema (`application/json`)

Delete Memory DELETE `/v1/memories/{memory_id}/`

Get Memory History GET `/v1/memories/{memory_id}/history/`

Batch Update & Batch Delete PUT DELETE `/v1/batch/`

Request Body Schema (`application/json`)

POST Create Organization (`/api/v1/orgs/organizations/`)

Request Body (`application/json`)

GETDELETE List, Get & Delete Organizations (`/api/v1/orgs/organizations/`)

POSTGET Organization Members (`/api/v1/orgs/organizations/{org_id}/members/`)

Request Body for `POST` (`application/json`)

POSTGET Create & List Projects (`/api/v1/orgs/organizations/{org_id}/projects/`)

Request Body for `POST` (`application/json`)

PATCHGET Update Project Governance (`/api/v1/orgs/organizations/{org_id}/projects/{project_id}/`)

Request Body for `PATCH` (`application/json`)

DELETE Delete Project (`/api/v1/orgs/organizations/{org_id}/projects/{project_id}/`)

GET List Entities & Users Directory (`/v1/entities/`)

DELETE Cascade-Delete Entity & Memories (`/v1/entities/{entity_type}/{entity_id}/`)

POSTGET Create & List Project Webhooks (`/api/v1/webhooks/projects/{project_id}/webhooks/`)

Request Body for `POST` (`application/json`)

PUTDELETE Update & Delete Webhook (`/api/v1/webhooks/webhooks/{webhook_id}/`)

GET Event Ledger & Operation Status (`/v1/events/` & `/v1/event/{event_id}/`)

POST Portable Memory Exports (`/v1/exports/` & `/v1/exports/get/`)

Request Body (`application/json`)

POST Submit Memory Relevance Feedback (`/v1/feedback/`)

Request Body (`application/json`)

POST Consolidate & Deduplicate Memories (`/v1/memories/consolidate/`)

Request Body (`application/json`)