{
  "openapi": "3.1.0",
  "info": {
    "title": "Blink Cloud API",
    "version": "1.0.0",
    "summary": "Agent-Native Semantic Memory & Code Intelligence API by FractionML",
    "description": "Production REST API for Blink Cloud (`https://api.fractionml.com`). Every endpoint enforces strict tenant isolation (`org_id`, `project_id`, `user_id`) and supports both `Authorization: Bearer <API_KEY>` and `Authorization: Token <API_KEY>` headers."
  },
  "servers": [
    {
      "url": "https://api.fractionml.com",
      "description": "Blink Cloud Global Edge API"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    },
    {
      "TokenAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass `Authorization: Bearer $BLINK_API_KEY`"
      },
      "TokenAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "description": "Pass `Authorization: Token $BLINK_API_KEY`"
      }
    }
  },
  "paths": {
    "/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check edge and origin health",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy"
          }
        }
      }
    },
    "/v1/blink/ingest": {
      "post": {
        "operationId": "blinkIngest",
        "tags": ["Blink Native Engine"],
        "summary": "Ingest a memory or code snippet into Blink Engine",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text", "user_id"],
                "properties": {
                  "text": { "type": "string", "description": "Memory text or source code snippet to index." },
                  "user_id": { "type": "string", "description": "Tenant user/workspace identifier." },
                  "project_id": { "type": "string", "description": "Optional project scope." },
                  "org_id": { "type": "string", "description": "Optional organization scope." },
                  "kind": { "type": "string", "default": "memory", "enum": ["memory", "code", "decision", "fact"] },
                  "metadata": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Memory indexed in GPU VRAM and durable storage"
          }
        }
      }
    },
    "/v1/blink/query": {
      "post": {
        "operationId": "blinkQuery",
        "tags": ["Blink Native Engine"],
        "summary": "Sub-5ms GPU semantic search over tenant memories",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query", "user_id"],
                "properties": {
                  "query": { "type": "string", "description": "Natural-language search query." },
                  "user_id": { "type": "string", "description": "Tenant user/workspace identifier." },
                  "project_id": { "type": "string" },
                  "org_id": { "type": "string" },
                  "top_k": { "type": "integer", "default": 5 },
                  "mode": { "type": "string", "default": "retrieve", "enum": ["retrieve", "synthesize"] },
                  "filters": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Ranked semantic memory results"
          }
        }
      }
    },
    "/v1/blink/forget": {
      "delete": {
        "operationId": "blinkForget",
        "tags": ["Blink Native Engine"],
        "summary": "Hard-delete a memory or entire tenant namespace from GPU VRAM and disk",
        "parameters": [
          { "name": "memory_id", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Memory or tenant bank deleted"
          }
        }
      }
    },
    "/v1/memories/": {
      "post": {
        "operationId": "addMemories",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Add memories from conversation messages or text",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["role", "content"],
                      "properties": {
                        "role": { "type": "string", "enum": ["user", "assistant", "system"] },
                        "content": { "type": "string" }
                      }
                    }
                  },
                  "text": { "type": "string" },
                  "user_id": { "type": "string" },
                  "agent_id": { "type": "string" },
                  "app_id": { "type": "string" },
                  "run_id": { "type": "string" },
                  "project_id": { "type": "string" },
                  "org_id": { "type": "string" },
                  "metadata": { "type": "object", "additionalProperties": true },
                  "infer": { "type": "boolean", "default": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Created memory events" }
        }
      },
      "get": {
        "operationId": "listMemories",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "List all memories for a tenant scope",
        "parameters": [
          { "name": "user_id", "in": "query", "schema": { "type": "string" } },
          { "name": "agent_id", "in": "query", "schema": { "type": "string" } },
          { "name": "app_id", "in": "query", "schema": { "type": "string" } },
          { "name": "run_id", "in": "query", "schema": { "type": "string" } },
          { "name": "project_id", "in": "query", "schema": { "type": "string" } },
          { "name": "org_id", "in": "query", "schema": { "type": "string" } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 100 } }
        ],
        "responses": {
          "200": { "description": "List of memory objects" }
        }
      },
      "delete": {
        "operationId": "deleteAllMemories",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Delete all memories matching a tenant scope",
        "parameters": [
          { "name": "user_id", "in": "query", "schema": { "type": "string" } },
          { "name": "agent_id", "in": "query", "schema": { "type": "string" } },
          { "name": "app_id", "in": "query", "schema": { "type": "string" } },
          { "name": "run_id", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Memories deleted" }
        }
      }
    },
    "/v2/memories/search/": {
      "post": {
        "operationId": "searchMemoriesV2",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Search memories with structured boolean/comparison filters",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string" },
                  "user_id": { "type": "string" },
                  "agent_id": { "type": "string" },
                  "app_id": { "type": "string" },
                  "run_id": { "type": "string" },
                  "top_k": { "type": "integer", "default": 10 },
                  "threshold": { "type": "number", "default": 0.0 },
                  "filters": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Ranked search results" }
        }
      }
    },
    "/v1/memories/{memory_id}/": {
      "get": {
        "operationId": "getMemory",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Retrieve a single memory by ID",
        "parameters": [
          { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Memory object" },
          "404": { "description": "Memory not found" }
        }
      },
      "put": {
        "operationId": "updateMemory",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Update a memory's text and metadata",
        "parameters": [
          { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string" },
                  "metadata": { "type": "object", "additionalProperties": true }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated memory object" }
        }
      },
      "delete": {
        "operationId": "deleteMemory",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Hard-delete a single memory by ID",
        "parameters": [
          { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Memory deleted" }
        }
      }
    },
    "/v1/memories/{memory_id}/history/": {
      "get": {
        "operationId": "getMemoryHistory",
        "tags": ["Mem0-Compatible Memories"],
        "summary": "Retrieve audit history of a memory",
        "parameters": [
          { "name": "memory_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Chronological list of mutations" }
        }
      }
    },
    "/v1/batch/": {
      "put": {
        "operationId": "batchUpdateMemories",
        "tags": ["Batch Operations"],
        "summary": "Batch update multiple memories in one call",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["memories"],
                "properties": {
                  "memories": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["memory_id", "text"],
                      "properties": {
                        "memory_id": { "type": "string" },
                        "text": { "type": "string" },
                        "metadata": { "type": "object", "additionalProperties": true }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Batch update confirmation" }
        }
      },
      "delete": {
        "operationId": "batchDeleteMemories",
        "tags": ["Batch Operations"],
        "summary": "Batch delete multiple memories in one call",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["memories"],
                "properties": {
                  "memories": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["memory_id"],
                      "properties": {
                        "memory_id": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Batch delete confirmation" }
        }
      }
    },
    "/api/v1/orgs/organizations/": {
      "post": {
        "operationId": "createOrganization",
        "tags": ["Platform Control Plane"],
        "summary": "Create a new Organization",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Organization created" } }
      },
      "get": {
        "operationId": "listOrganizations",
        "tags": ["Platform Control Plane"],
        "summary": "List all Organizations",
        "responses": { "200": { "description": "Organizations list" } }
      }
    },
    "/api/v1/orgs/organizations/{org_id}/projects/": {
      "post": {
        "operationId": "createProject",
        "tags": ["Platform Control Plane"],
        "summary": "Create a Project inside an Organization",
        "parameters": [
          { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name"],
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" },
                  "custom_instructions": { "type": "string" },
                  "custom_categories": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Project created" } }
      },
      "get": {
        "operationId": "listProjects",
        "tags": ["Platform Control Plane"],
        "summary": "List Projects in an Organization",
        "parameters": [
          { "name": "org_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Projects list" } }
      }
    },
    "/v1/entities/": {
      "get": {
        "operationId": "listEntities",
        "tags": ["Platform Control Plane"],
        "summary": "List active tenant entities (users, agents, apps, runs)",
        "parameters": [
          { "name": "org_id", "in": "query", "schema": { "type": "string" } },
          { "name": "project_id", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Entity list" } }
      }
    },
    "/api/v1/webhooks/projects/{project_id}/webhooks/": {
      "post": {
        "operationId": "createWebhook",
        "tags": ["Platform Control Plane"],
        "summary": "Register a project webhook for memory events",
        "parameters": [
          { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "url", "event_types"],
                "properties": {
                  "name": { "type": "string" },
                  "url": { "type": "string" },
                  "event_types": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        },
        "responses": { "201": { "description": "Webhook created" } }
      },
      "get": {
        "operationId": "listWebhooks",
        "tags": ["Platform Control Plane"],
        "summary": "List registered webhooks for a project",
        "parameters": [
          { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Webhooks list" } }
      }
    },
    "/v1/exports/": {
      "post": {
        "operationId": "createExport",
        "tags": ["Platform Control Plane"],
        "summary": "Create a structured memory export snapshot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "filters": { "type": "object", "additionalProperties": true },
                  "schema": { "type": "object", "additionalProperties": true },
                  "org_id": { "type": "string" },
                  "project_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Export job created" } }
      },
      "get": {
        "operationId": "getExport",
        "tags": ["Platform Control Plane"],
        "summary": "Download export snapshot",
        "parameters": [
          { "name": "export_id", "in": "query", "schema": { "type": "string" } },
          { "name": "org_id", "in": "query", "schema": { "type": "string" } },
          { "name": "project_id", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Export payload" } }
      }
    },
    "/v1/feedback/": {
      "post": {
        "operationId": "submitFeedback",
        "tags": ["Platform Control Plane"],
        "summary": "Record relevance feedback on a memory",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["memory_id", "feedback"],
                "properties": {
                  "memory_id": { "type": "string" },
                  "feedback": { "type": "string", "enum": ["POSITIVE", "NEGATIVE", "VERY_POSITIVE", "VERY_NEGATIVE"] },
                  "feedback_reason": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Feedback recorded" } }
      }
    },
    "/v1/memories/consolidate/": {
      "post": {
        "operationId": "consolidateMemories",
        "tags": ["Consolidation"],
        "summary": "Deduplicate and merge redundant memories for a tenant",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["user_id"],
                "properties": {
                  "user_id": { "type": "string" },
                  "similarity_threshold": { "type": "number", "default": 0.92 }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Consolidation summary" } }
      }
    }
  }
}