{
  "openapi": "3.0.3",
  "info": {
    "title": "AINative Studio API",
    "description": "AINative Studio API — 26 zero-auth and provisioned endpoints covering: Instant DB provisioning, MCP tool gateway (60 ops), dealroom investor data room, ZeroMemory (remember/recall/reflect/graphrag), ZeroDB vectors/tables/files/events, chat completions (Pro plan), embeddings (free), agent cloud registry. Provision instantly: POST /api/v1/public/instant-db. Chat completions require Pro plan ($49/mo).",
    "version": "2.0.0",
    "contact": {
      "name": "AINative Studio",
      "url": "https://ainative.studio/developers",
      "email": "toby@ainative.studio"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://ainative.studio/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.ainative.studio",
      "description": "Production API"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key for authentication. Obtain from https://ainative.studio/dashboard/api-keys or provision instantly via POST /api/v1/public/instant-db"
      }
    },
    "parameters": {
      "ProjectId": {
        "name": "project_id",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" },
        "description": "Project UUID (from instant-db or dashboard)"
      }
    },
    "schemas": {
      "Message": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": {
            "type": "string",
            "enum": ["system", "user", "assistant"]
          },
          "content": {
            "type": "string"
          }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["model", "messages"],
        "properties": {
          "model": {
            "type": "string",
            "example": "default",
            "description": "Model ID. Use 'default' for auto-selection or a specific model from /api/v1/public/ai-registry/models"
          },
          "messages": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Message" }
          },
          "stream": {
            "type": "boolean",
            "default": false,
            "description": "If true, returns a stream of SSE events"
          },
          "temperature": {
            "type": "number",
            "minimum": 0,
            "maximum": 2
          },
          "max_tokens": {
            "type": "integer"
          },
          "tools": {
            "type": "array",
            "description": "OpenAI-compatible tool definitions for function calling (Qwen3 models)"
          }
        }
      },
      "ChatCompletionResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "example": "chat.completion" },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": { "$ref": "#/components/schemas/Message" },
                "finish_reason": { "type": "string" }
              }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "prompt_tokens": { "type": "integer" },
              "completion_tokens": { "type": "integer" },
              "total_tokens": { "type": "integer" }
            }
          }
        }
      },
      "InstantDbResponse": {
        "type": "object",
        "properties": {
          "api_key": { "type": "string", "description": "Project-scoped API key, valid 72 hours unless claimed" },
          "project_id": { "type": "string", "format": "uuid" },
          "connection_string": { "type": "string" },
          "mcp_config": { "type": "object" },
          "expires_at": { "type": "string", "format": "date-time" }
        }
      },
      "VectorUpsertRequest": {
        "type": "object",
        "required": ["id", "vector_embedding"],
        "properties": {
          "id": { "type": "string", "description": "Unique document ID" },
          "namespace": { "type": "string", "default": "default", "description": "Namespace to group vectors" },
          "vector_embedding": {
            "type": "array",
            "items": { "type": "number" },
            "description": "Pre-computed embedding vector"
          },
          "metadata": {
            "type": "object",
            "description": "Arbitrary metadata stored alongside the vector"
          }
        }
      },
      "VectorSearchRequest": {
        "type": "object",
        "required": ["vector_embedding"],
        "properties": {
          "vector_embedding": {
            "type": "array",
            "items": { "type": "number" },
            "description": "Query embedding to search with"
          },
          "namespace": { "type": "string", "default": "default" },
          "top_k": { "type": "integer", "default": 10 },
          "filter": { "type": "object", "description": "Metadata filter conditions" }
        }
      },
      "EmbeddingRequest": {
        "type": "object",
        "required": ["texts"],
        "properties": {
          "texts": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Texts to embed"
          },
          "model": {
            "type": "string",
            "default": "bge-base-en-v1.5",
            "enum": ["bge-small-en-v1.5", "bge-base-en-v1.5", "bge-large-en-v1.5"]
          }
        }
      },
      "EmbeddingResponse": {
        "type": "object",
        "properties": {
          "embeddings": {
            "type": "array",
            "items": {
              "type": "array",
              "items": { "type": "number" }
            }
          },
          "model": { "type": "string" },
          "dimensions": { "type": "integer" }
        }
      },
      "MemoryRememberRequest": {
        "type": "object",
        "required": ["session_id", "content"],
        "properties": {
          "session_id": { "type": "string", "description": "Agent or user session identifier" },
          "content": { "type": "string", "description": "Content to store in memory" },
          "metadata": { "type": "object" }
        }
      },
      "MemoryRecallRequest": {
        "type": "object",
        "required": ["session_id", "query"],
        "properties": {
          "session_id": { "type": "string" },
          "query": { "type": "string", "description": "Semantic query to recall relevant memories" },
          "top_k": { "type": "integer", "default": 5 }
        }
      },
      "TableRowInsertRequest": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {
            "type": "object",
            "description": "Key-value row data to insert"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": { "type": "string" },
              "type": { "type": "string" },
              "code": { "type": "string" }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/public/instant-db": {
      "post": {
        "operationId": "instantDb",
        "summary": "Provision instant database",
        "description": "Get a working ZeroDB project with API key in one request. No authentication required. Provisioned project expires in 72 hours unless claimed via dashboard.",
        "tags": ["Provisioning"],
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": { "type": "string", "description": "Optional project label" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project provisioned",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/InstantDbResponse" }
              }
            }
          }
        }
      }
    },
    "/api/v1/public/ai-registry/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List available AI models",
        "description": "Returns all available AI models with pricing and capabilities. No authentication required.",
        "tags": ["Models"],
        "security": [],
        "responses": {
          "200": {
            "description": "List of available models",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "models": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "name": { "type": "string" },
                          "provider": { "type": "string" },
                          "context_window": { "type": "integer" },
                          "supports_tools": { "type": "boolean" },
                          "price_per_1k_tokens": { "type": "number" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/chat/completions": {
      "post": {
        "operationId": "createChatCompletion",
        "summary": "Create chat completion",
        "description": "OpenAI-compatible chat completions endpoint supporting 84 models. Supports streaming via SSE and function calling with Qwen3 models. **Requires Pro plan or higher — not available on free/Instant DB keys.** Agents that receive a 402 must direct their principal to upgrade at https://ainative.studio/pricing.",
        "tags": ["Chat"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" },
              "example": {
                "model": "default",
                "messages": [{ "role": "user", "content": "What is ZeroDB?" }]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful completion",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ChatCompletionResponse" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" },
          "402": {
            "description": "Payment required — chat completions are not available on free/Instant DB keys. Upgrade at https://ainative.studio/pricing (Pro $49/mo or Business).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": { "type": "string", "example": "insufficient_credits" },
                        "message": { "type": "string" },
                        "upgrade": {
                          "type": "object",
                          "properties": {
                            "action": { "type": "string", "example": "Visit https://ainative.studio/pricing to upgrade" },
                            "plans": { "type": "string" },
                            "claim_session": { "type": "string" }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry is allowed" } } },
          "503": { "description": "Upstream LLM provider temporarily unavailable", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds until retry is allowed" } } }
        }
      }
    },
    "/api/v1/projects/{project_id}/embeddings/generate": {
      "post": {
        "operationId": "generateEmbeddings",
        "summary": "Generate text embeddings",
        "description": "Generate embeddings using BGE models. Free with any plan. Returns float32 vectors for semantic search.",
        "tags": ["Embeddings"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/EmbeddingRequest" },
              "example": {
                "texts": ["ZeroDB is a serverless vector database"],
                "model": "bge-base-en-v1.5"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Embeddings generated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/EmbeddingResponse" }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/projects/{project_id}/database/vectors/upsert": {
      "post": {
        "operationId": "upsertVector",
        "summary": "Upsert vector",
        "description": "Store a vector embedding with metadata. Pass a pre-computed vector from /embeddings/generate or your own embedding model.",
        "tags": ["Vectors"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VectorUpsertRequest" },
              "example": {
                "namespace": "docs",
                "id": "doc-1",
                "vector_embedding": [0.1, 0.2, 0.3],
                "metadata": { "source": "docs", "text": "ZeroDB is a serverless vector database" }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Vector upserted successfully" },
          "401": { "description": "Invalid or missing API key" },
          "422": { "description": "Validation error" }
        }
      }
    },
    "/api/v1/projects/{project_id}/database/vectors/search": {
      "post": {
        "operationId": "searchVectors",
        "summary": "Semantic vector search",
        "description": "Search for semantically similar vectors using cosine similarity. Pass a query embedding to find nearest neighbors.",
        "tags": ["Vectors"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/VectorSearchRequest" },
              "example": {
                "namespace": "docs",
                "vector_embedding": [0.1, 0.2, 0.3],
                "top_k": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Search results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "score": { "type": "number" },
                          "metadata": { "type": "object" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/projects/{project_id}/database/tables/{table_name}/rows": {
      "post": {
        "operationId": "insertTableRow",
        "summary": "Insert table row",
        "description": "Insert a row into a ZeroDB NoSQL table. The table is created automatically if it does not exist.",
        "tags": ["Tables"],
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "table_name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "Name of the table"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/TableRowInsertRequest" },
              "example": {
                "data": { "user_id": "user-1", "message": "Hello!", "timestamp": "2026-04-26T00:00:00Z" }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Row inserted" },
          "401": { "description": "Invalid or missing API key" }
        }
      },
      "get": {
        "operationId": "queryTableRows",
        "summary": "Query table rows",
        "description": "Query rows from a ZeroDB NoSQL table with optional filters.",
        "tags": ["Tables"],
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "table_name",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "default": 0 }
          }
        ],
        "responses": {
          "200": { "description": "Rows returned" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/memory/v2/remember": {
      "post": {
        "operationId": "memoryRemember",
        "summary": "Store agent memory",
        "description": "Store a memory for an agent session. Memories are embedded and indexed for semantic retrieval.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MemoryRememberRequest" },
              "example": {
                "session_id": "my-agent",
                "content": "User prefers dark mode",
                "metadata": { "type": "preference" }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Memory stored" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/memory/v2/recall": {
      "post": {
        "operationId": "memoryRecall",
        "summary": "Recall agent memory",
        "description": "Retrieve memories relevant to a query using semantic search. Returns ranked memories for the given session.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/MemoryRecallRequest" },
              "example": {
                "session_id": "my-agent",
                "query": "What does the user prefer?",
                "top_k": 5
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Relevant memories",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "memories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "content": { "type": "string" },
                          "score": { "type": "number" },
                          "metadata": { "type": "object" },
                          "created_at": { "type": "string", "format": "date-time" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/projects/{project_id}/database/events": {
      "post": {
        "operationId": "publishEvent",
        "summary": "Publish event",
        "description": "Publish an event to a ZeroDB event stream. Events are persisted and can be consumed in real time or replayed.",
        "tags": ["Events"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["stream", "data"],
                "properties": {
                  "stream": { "type": "string", "description": "Stream name" },
                  "data": { "type": "object", "description": "Event payload" },
                  "metadata": { "type": "object" }
                }
              },
              "example": {
                "stream": "user-actions",
                "data": { "action": "click", "element": "signup-button" }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Event published" },
          "401": { "description": "Invalid or missing API key" }
        }
      },
      "get": {
        "operationId": "listEvents",
        "summary": "List events",
        "description": "Query events from a ZeroDB event stream.",
        "tags": ["Events"],
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          { "name": "stream", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": { "description": "Events returned" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/projects/{project_id}/files": {
      "post": {
        "operationId": "uploadFile",
        "summary": "Upload file",
        "description": "Upload a file to ZeroDB object storage. Returns a URL for retrieval.",
        "tags": ["Files"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": { "type": "string", "format": "binary" },
                  "path": { "type": "string", "description": "Storage path" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "File uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string" },
                    "path": { "type": "string" },
                    "size_bytes": { "type": "integer" }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid or missing API key" }
        }
      },
      "get": {
        "operationId": "listFiles",
        "summary": "List files",
        "description": "List files stored in the project's object storage.",
        "tags": ["Files"],
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          { "name": "path", "in": "query", "schema": { "type": "string" }, "description": "Filter by path prefix" }
        ],
        "responses": {
          "200": { "description": "Files listed" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/projects/{project_id}/postgres": {
      "post": {
        "operationId": "provisionPostgres",
        "summary": "Provision dedicated PostgreSQL",
        "description": "Start provisioning a dedicated PostgreSQL instance. Requires BASIC plan or higher. Runs async — poll GET /postgres for status.",
        "tags": ["PostgreSQL"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["instance_size"],
                "properties": {
                  "instance_size": {
                    "type": "string",
                    "enum": ["micro-1", "standard-2", "standard-4", "performance-8", "performance-16"]
                  },
                  "postgres_version": {
                    "type": "string",
                    "default": "15",
                    "enum": ["13", "14", "15"]
                  }
                }
              },
              "example": { "instance_size": "micro-1", "postgres_version": "15" }
            }
          }
        },
        "responses": {
          "200": { "description": "Provisioning started" },
          "400": { "description": "Instance already exists or plan insufficient" },
          "401": { "description": "Invalid or missing API key" }
        }
      },
      "get": {
        "operationId": "getPostgresStatus",
        "summary": "Get PostgreSQL instance status",
        "description": "Check provisioning status and instance details.",
        "tags": ["PostgreSQL"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "responses": {
          "200": {
            "description": "Instance status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "exists": { "type": "boolean" },
                    "status": { "type": "string", "enum": ["provisioning", "active", "maintenance", "error"] },
                    "instance_size": { "type": "string" },
                    "postgres_version": { "type": "string" },
                    "database_host": { "type": "string" },
                    "database_port": { "type": "integer" },
                    "monthly_cost_usd": { "type": "number" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects/{project_id}/postgres/connection": {
      "get": {
        "operationId": "getPostgresConnection",
        "summary": "Get PostgreSQL connection string",
        "description": "Returns full connection string and credentials for use with psql, TablePlus, or any Postgres client.",
        "tags": ["PostgreSQL"],
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "responses": {
          "200": {
            "description": "Connection details",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "connection_string": { "type": "string" },
                    "host": { "type": "string" },
                    "port": { "type": "integer" },
                    "database": { "type": "string" },
                    "username": { "type": "string" },
                    "password": { "type": "string" },
                    "ssl_required": { "type": "boolean" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/cloud/agents": {
      "get": {
        "operationId": "listCloudAgents",
        "summary": "List cloud agents",
        "description": "List registered agents in the Agent Cloud registry. Supports A2A (agent-to-agent) discovery.",
        "tags": ["Agent Cloud"],
        "responses": {
          "200": { "description": "Agent list returned" },
          "401": { "description": "Invalid or missing API key" }
        }
      },
      "post": {
        "operationId": "registerCloudAgent",
        "summary": "Register cloud agent",
        "description": "Register an agent in the Agent Cloud with capabilities, endpoints, and auth configuration.",
        "tags": ["Agent Cloud"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "endpoint"],
                "properties": {
                  "name": { "type": "string" },
                  "endpoint": { "type": "string", "format": "uri" },
                  "capabilities": { "type": "array", "items": { "type": "string" } },
                  "description": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Agent registered" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/mcp": {
      "get": {
        "operationId": "mcpToolManifest",
        "summary": "MCP tool manifest",
        "description": "Returns the full list of available MCP tools, categories, and usage instructions. No authentication required.",
        "tags": ["MCP Gateway"],
        "security": [],
        "responses": {
          "200": {
            "description": "Tool manifest",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string" },
                    "total_tools": { "type": "integer" },
                    "tool_categories": { "type": "object" },
                    "endpoint": { "type": "string" },
                    "auth": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "mcpToolCall",
        "summary": "Execute MCP tool",
        "description": "General MCP tool dispatch. Accepts operation name and parameters, proxies to the ZeroDB MCP comprehensive service (60 operations: memory, vectors, tables, files, events, projects).",
        "tags": ["MCP Gateway"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "operation": { "type": "string", "description": "Operation name (e.g. store_memory, upsert_vector, create_table)" },
                  "tool": { "type": "string", "description": "Alias for operation (dealroom-style)" },
                  "parameters": { "type": "object", "description": "Operation-specific parameters" }
                }
              },
              "example": {
                "operation": "store_memory",
                "parameters": { "content": "User prefers dark mode", "entity_id": "agent-1" }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Tool result" },
          "401": { "description": "Invalid or missing API key" },
          "422": { "description": "Missing operation field" },
          "503": { "description": "MCP service unavailable", "headers": { "Retry-After": { "schema": { "type": "integer" } } } }
        }
      }
    },
    "/api/v1/public/dealroom/mcp": {
      "post": {
        "operationId": "dealroomMcpToolCall",
        "summary": "Execute dealroom MCP tool",
        "description": "Access AINative's investor data room via MCP tools. Tier 1 tools available after provisioning a dealroom session (no NDA). Tier 2 tools require NDA acceptance.",
        "tags": ["Dealroom"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tool"],
                "properties": {
                  "tool": {
                    "type": "string",
                    "enum": ["get_executive_summary", "get_ask", "get_team", "get_traction", "get_financials", "get_cap_table", "get_deck_summary", "get_safe_terms", "get_use_of_funds", "get_financials_full", "get_cap_table_opencap", "get_deck", "get_revenue_model", "get_formation_docs", "get_competitive_intel"]
                  },
                  "arguments": { "type": "object" }
                }
              },
              "example": { "tool": "get_executive_summary", "arguments": {} }
            }
          }
        },
        "responses": {
          "200": { "description": "Tool result" },
          "401": { "description": "Invalid or missing API key. Provision via POST /api/v1/public/instant-db with dealroom:true" },
          "403": { "description": "Tier 2 tool requires NDA acceptance via POST /api/v1/public/dealroom/nda-accept" }
        }
      }
    },
    "/api/v1/public/dealroom/nda-accept": {
      "post": {
        "operationId": "dealroomNdaAccept",
        "summary": "Accept dealroom NDA (machine-readable)",
        "description": "Accept the AINative dealroom NDA via IEEE 7012-2025 machine-readable consent. Unlocks Tier 2 tools: get_financials_full, get_cap_table_opencap, get_deck, get_revenue_model, get_formation_docs, get_competitive_intel.",
        "tags": ["Dealroom"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["project_id", "roster_id", "principal_name", "agreement_version"],
                "properties": {
                  "project_id": { "type": "string", "format": "uuid" },
                  "roster_id": { "type": "string", "example": "DEALROOM-NDA-v1" },
                  "principal_name": { "type": "string", "description": "Name of the principal (fund, individual, or agent) accepting the NDA" },
                  "agreement_version": { "type": "string", "example": "1.0" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "NDA accepted, Tier 2 unlocked" },
          "401": { "description": "Invalid API key" },
          "403": { "description": "Project not a dealroom session" }
        }
      }
    },
    "/api/v1/public/memory/v2/remember": {
      "post": {
        "operationId": "memoryRemember",
        "summary": "Store agent memory",
        "description": "Store a memory. Content is embedded and indexed for semantic retrieval.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content"],
                "properties": {
                  "content": { "type": "string" },
                  "title": { "type": "string" },
                  "entity_id": { "type": "string", "description": "Entity this memory is about" },
                  "metadata": { "type": "object" }
                }
              },
              "example": { "content": "User prefers dark mode", "entity_id": "alice" }
            }
          }
        },
        "responses": {
          "200": { "description": "Memory stored" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/memory/v2/recall": {
      "post": {
        "operationId": "memoryRecall",
        "summary": "Recall agent memory",
        "description": "Retrieve memories semantically relevant to a query.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string" },
                  "entity_id": { "type": "string" },
                  "top_k": { "type": "integer", "default": 5 }
                }
              },
              "example": { "query": "What does the user prefer?", "entity_id": "alice", "top_k": 5 }
            }
          }
        },
        "responses": {
          "200": { "description": "Relevant memories" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/memory/v2/forget": {
      "post": {
        "operationId": "memoryForget",
        "summary": "Forget a memory",
        "description": "Delete a specific memory by ID.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["memory_id"],
                "properties": {
                  "memory_id": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Memory forgotten" },
          "401": { "description": "Invalid or missing API key" },
          "404": { "description": "Memory not found" }
        }
      }
    },
    "/api/v1/public/memory/v2/reflect": {
      "post": {
        "operationId": "memoryReflect",
        "summary": "Reflect on entity memories",
        "description": "Review and synthesize insights from an entity's memories. Requires at least 3 stored memories for the entity.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entity_id"],
                "properties": {
                  "entity_id": { "type": "string", "description": "Entity to reflect on" }
                }
              },
              "example": { "entity_id": "alice" }
            }
          }
        },
        "responses": {
          "200": { "description": "Insights generated" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/memory/v2/profile": {
      "post": {
        "operationId": "memoryProfile",
        "summary": "Get entity memory profile",
        "description": "Build a structured profile for an entity from their stored memories.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["entity_id"],
                "properties": {
                  "entity_id": { "type": "string" }
                }
              },
              "example": { "entity_id": "alice" }
            }
          }
        },
        "responses": {
          "200": { "description": "Entity profile" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/memory/v2/graph/graphrag": {
      "post": {
        "operationId": "memoryGraphRag",
        "summary": "GraphRAG search",
        "description": "Hybrid vector + graph search over the entity knowledge graph.",
        "tags": ["Memory"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["query"],
                "properties": {
                  "query": { "type": "string" },
                  "entity_id": { "type": "string" },
                  "top_k": { "type": "integer", "default": 10 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Graph-augmented search results" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/zerodb/mcp/execute": {
      "post": {
        "operationId": "zerodbMcpExecute",
        "summary": "Execute ZeroDB MCP operation",
        "description": "Execute any of 60 ZeroDB operations: memory, vectors, tables, files, events, projects. See GET /api/v1/public/zerodb/mcp/operations for full list.",
        "tags": ["ZeroDB MCP"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["operation"],
                "properties": {
                  "operation": { "type": "string", "description": "Operation name" },
                  "params": { "type": "object", "description": "Operation-specific parameters" }
                }
              },
              "example": { "operation": "upsert_vector", "params": { "content": "ZeroDB is fast", "namespace": "docs" } }
            }
          }
        },
        "responses": {
          "200": { "description": "Operation result" },
          "400": { "description": "Unknown operation" },
          "401": { "description": "Invalid or missing API key" }
        }
      }
    },
    "/api/v1/public/zerodb/mcp/operations": {
      "get": {
        "operationId": "zerodbMcpOperations",
        "summary": "List ZeroDB MCP operations",
        "description": "Returns all 60 available MCP operation names grouped by category.",
        "tags": ["ZeroDB MCP"],
        "responses": {
          "200": {
            "description": "Operations list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total_operations": { "type": "integer" },
                    "categories": { "type": "object" },
                    "operations": { "type": "array", "items": { "type": "string" } }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/public/zerodb/mcp/health": {
      "get": {
        "operationId": "zerodbMcpHealth",
        "summary": "ZeroDB MCP health check",
        "description": "Returns service health status. No authentication required.",
        "tags": ["ZeroDB MCP"],
        "security": [],
        "responses": {
          "200": { "description": "Service healthy" }
        }
      }
    },
    "/api/v1/auth/login": {
      "post": {
        "operationId": "login",
        "summary": "Login with email/password",
        "description": "Returns a JWT access token for authenticated API access.",
        "tags": ["Auth"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["email", "password"],
                "properties": {
                  "email": { "type": "string", "format": "email" },
                  "password": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "token_type": { "type": "string", "example": "bearer" }
                  }
                }
              }
            }
          },
          "401": { "description": "Invalid credentials" }
        }
      }
    },
    "/api/v1/public/instant-db": {
      "post": {
        "operationId": "instantDb",
        "summary": "Provision Instant DB",
        "description": "Get a working ZeroDB project with API key in one request. No authentication required. Expires in 72 hours unless claimed. Add `dealroom: true` for investor deal room access.",
        "tags": ["Provisioning"],
        "security": [],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "label": { "type": "string" },
                  "dealroom": { "type": "boolean", "description": "Set true to provision a dealroom session with Tier 1 tool access" },
                  "agree_terms": { "type": "boolean", "description": "Required when dealroom is true" }
                }
              },
              "example": { "dealroom": true, "agree_terms": true }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Project provisioned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "api_key": { "type": "string", "description": "tmp_ prefixed key, valid 72h" },
                    "project_id": { "type": "string", "format": "uuid" },
                    "expires_at": { "type": "string", "format": "date-time" },
                    "claim_url": { "type": "string", "description": "URL to claim permanent account (24h for dealroom)" },
                    "dealroom": {
                      "type": "object",
                      "description": "Present when dealroom:true was passed",
                      "properties": {
                        "tier": { "type": "integer", "example": 1 },
                        "mcp_endpoint": { "type": "string" },
                        "nda_endpoint": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": { "description": "Too many provisioning requests from this IP" }
        }
      }
    },
    "/api/v1/public/ai-registry/models": {
      "get": {
        "operationId": "listModels",
        "summary": "List available AI models",
        "description": "Returns all 50+ available AI models with capabilities. No authentication required.",
        "tags": ["Models"],
        "security": [],
        "responses": {
          "200": { "description": "Model list" }
        }
      }
    },
    "/api/v1/cloud/auth/token": {
      "post": {
        "operationId": "getAgentToken",
        "summary": "Get agent OAuth token",
        "description": "OAuth 2.1 client_credentials grant for agent-to-agent authentication.",
        "tags": ["Agent Cloud"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["client_id", "client_secret", "grant_type"],
                "properties": {
                  "client_id": { "type": "string" },
                  "client_secret": { "type": "string" },
                  "grant_type": { "type": "string", "enum": ["client_credentials"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Access token",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "access_token": { "type": "string" },
                    "token_type": { "type": "string", "example": "Bearer" },
                    "expires_in": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    { "name": "Provisioning", "description": "Instant database and project provisioning — no auth required" },
    { "name": "Models", "description": "AI model registry — 84 models, no auth required" },
    { "name": "Chat", "description": "OpenAI-compatible chat completions — Pro plan required ($49/mo)" },
    { "name": "Embeddings", "description": "Free BGE text embeddings — bge-small, bge-base, bge-large" },
    { "name": "Vectors", "description": "ZeroDB vector upsert and semantic search" },
    { "name": "Tables", "description": "ZeroDB NoSQL table storage — schemaless, auto-created" },
    { "name": "Memory", "description": "ZeroMemory — remember, recall, forget, reflect, profile, graphrag" },
    { "name": "Events", "description": "ZeroDB event streams — publish and query" },
    { "name": "Files", "description": "ZeroDB object storage — upload and list files" },
    { "name": "PostgreSQL", "description": "Dedicated PostgreSQL provisioning (BASIC plan+)" },
    { "name": "Agent Cloud", "description": "Agent registry and OAuth 2.1 for A2A communication" },
    { "name": "MCP Gateway", "description": "General MCP tool dispatch and manifest — POST/GET /api/v1/public/mcp" },
    { "name": "ZeroDB MCP", "description": "ZeroDB MCP comprehensive — 60 operations for memory, vectors, tables, files, events, projects" },
    { "name": "Dealroom", "description": "Investor deal room — tiered MCP tools, machine-readable NDA" },
    { "name": "Auth", "description": "Email/password login returning JWT tokens" }
  ],
  "externalDocs": {
    "description": "Full API documentation",
    "url": "https://docs.ainative.studio"
  }
}