{ "openapi": "3.0.3", "info": { "title": "Agent Architects Studio API", "description": "OpenAPI specification dynamically generated from the master API schema, enabling centralized management of AI agents, documents, long-term memory, and multi-agent workflows.", "version": "1.0.0", "contact": { "name": "API Support", "url": "https://themanhattanproject.ai" } }, "servers": [ { "url": "https://themanhattanproject.ai", "description": "Production Server" }, { "url": "http://localhost:1078", "description": "Local Development Server" } ], "tags": [ { "name": "Agents", "description": "Core AI agent creation, lifecycle management, and chat inference endpoints." }, { "name": "Documents", "description": "Vector knowledge base ingestion and semantic search management." }, { "name": "Memory", "description": "Long-term structured memory lifecycle and hybrid retrieval units." }, { "name": "Analytics & Stats", "description": "Volume, activity tracking, and real-time API usage analytics." }, { "name": "Bulk Operations", "description": "High-volume batch insertion and memory pagination capabilities." }, { "name": "Data Portability", "description": "Backup, migration, and AI-generated summary tools." }, { "name": "API Test Examples", "description": "Connectivity verification and sample utility controllers." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Enter your API key as a Bearer token in the Authorization header. Example: Bearer sk-..." } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/create_agent": { "post": { "tags": [ "Agents" ], "summary": "Create agent", "description": "Create a new agent. Authorization typically required in headers.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "agent_id": "string" } } } } } }, "x-when-to-use": "Call this when onboarding a new user, project, or tenant that needs its own isolated AI assistant with separate knowledge and memory.", "x-use-cases": [ "Onboarding a new customer with a dedicated support agent", "Creating a per-user personalised assistant in a SaaS app", "Spinning up a project-specific agent that only knows about that project's documents", "Multi-tenant platforms: one agent per organisation or workspace" ], "x-notes": "agent_slug must be unique across your account and URL-safe (lowercase letters and hyphens only). Store the returned agent_id \u2014 it is required by every other endpoint.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_name": { "type": "string", "example": "string" }, "agent_slug": { "type": "string", "example": "string" }, "permissions": { "type": "object", "example": {} }, "limits": { "type": "object", "example": {} }, "system-prompt": { "type": "string", "example": "string" } } } } } } } }, "/agent_chat": { "post": { "tags": [ "Agents" ], "summary": "Chat with agent", "description": "Send a message to a specific agent and receive a reply from the agent. Provide 'agent_id' and 'message' (optional 'options').", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "reply": "string", "conversation_id": "string" } } } } } }, "x-when-to-use": "Call this whenever the end-user sends a message. It is the primary inference endpoint \u2014 it combines the agent's documents, memory, and the current conversation to produce a contextual reply.", "x-use-cases": [ "Customer support chat widget backed by a product knowledge base", "Personal AI assistant that recalls previous conversations", "Domain-specific Q&A bot powered by uploaded documents", "Automated email-reply drafting with full conversation context" ], "x-notes": "This endpoint triggers LLM inference and may take 2\u201330 seconds. Use a client timeout of at least 120 seconds. Store the returned conversation_id and pass it on subsequent turns to maintain context continuity.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" }, "options": { "type": "object", "example": {} } } } } } } } }, "/list_agents": { "get": { "tags": [ "Agents" ], "summary": "List agents (API key)", "description": "List agents available to the provided API key (Authorization header).", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "agents": [] } } } } } }, "x-when-to-use": "Use at app startup to discover existing agents, populate an agent-picker UI, or verify an agent exists before making further calls.", "x-use-cases": [ "Populating an agent dropdown/switcher in your UI", "Auditing all active agents in your account", "Verifying that a specific agent_slug has already been created", "Syncing your local state with the server after a session restart" ], "x-notes": "Returns only agents associated with the API key used. Both enabled and disabled agents are included \u2014 filter on the 'enabled' field client-side if you want active-only results." } }, "/get_agent": { "get": { "tags": [ "Agents" ], "summary": "Get agent by id", "description": "Retrieve a single agent by ID. Example shows a GET with JSON payload as used in tests (some servers accept JSON body on GET).", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "agent": {} } } } } } }, "x-when-to-use": "Call this to retrieve full details of a specific agent, including its configuration, permissions, limits, and current status.", "x-use-cases": [ "Displaying agent settings in an admin dashboard", "Verifying agent configuration before making updates", "Checking whether an agent is enabled or disabled before sending it traffic" ], "x-notes": "Pass agent_id as a query parameter. The response includes all agent fields including description, permissions, limits, and timestamps. Returns 404 if the agent does not exist.", "parameters": [ { "name": "agent_id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "string" } ] } }, "/update_agent": { "post": { "tags": [ "Agents" ], "summary": "Update agent details", "description": "Update updatable fields for an agent. Authorization required.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true } } } } } }, "x-when-to-use": "Call this to modify an existing agent's configuration such as its description, permissions, or rate limits without recreating it.", "x-use-cases": [ "Updating an agent's description after a product change", "Adjusting rate limits for an agent that is experiencing higher traffic", "Changing permissions to grant or revoke capabilities", "Renaming an agent for organizational purposes" ], "x-notes": "Only include fields you want to change in the updates object \u2014 omitted fields remain unchanged. agent_slug and agent_id cannot be modified after creation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "updates": { "type": "object", "example": {} } } } } } } } }, "/disable_agent": { "post": { "tags": [ "Agents" ], "summary": "Disable agent", "description": "Disable an agent by id using Authorization header.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true } } } } } }, "x-when-to-use": "Call this to temporarily suspend an agent without deleting it. Disabled agents reject all chat and memory requests but retain their data.", "x-use-cases": [ "Suspending a misbehaving agent while investigating an issue", "Pausing an agent during scheduled maintenance", "Temporarily blocking an agent when a customer's subscription lapses" ], "x-notes": "Disabling is non-destructive \u2014 all documents and memories are preserved. Re-enable with /enable_agent at any time. Disabled agents will return 404 to agent_chat callers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" } } } } } } } }, "/enable_agent": { "post": { "tags": [ "Agents" ], "summary": "Enable agent", "description": "Enable an agent by id using Authorization header.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true } } } } } }, "x-when-to-use": "Call this to re-activate a previously disabled agent so it can accept chat and memory requests again.", "x-use-cases": [ "Re-enabling an agent after resolving an operational issue", "Restoring service after a customer renews their subscription", "Bringing an agent back online after maintenance" ], "x-notes": "Only works on agents that are currently disabled. If the agent is already enabled this is a no-op (returns ok). The agent resumes with all its previous documents and memories intact.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" } } } } } } } }, "/delete_agent": { "post": { "tags": [ "Agents" ], "summary": "Delete agent (permanent)", "description": "Permanently delete an agent by id for the authenticated user. Will also attempt to remove associated vector DB collections.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "agent_deleted" } } } } } }, "x-when-to-use": "Use only when the agent and all its data (documents, memory, conversations) should be permanently removed. Prefer disable_agent for temporary suspension.", "x-use-cases": [ "GDPR / right-to-erasure request \u2014 remove a user's entire AI profile", "Cleaning up test agents in a development environment", "Off-boarding a customer and purging their data" ], "x-notes": "This action is irreversible. It also attempts to delete the agent's vector DB collections. If vector deletion fails, the agent record is still removed from the database. Consider disable_agent if you may need to restore the agent later.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" } } } } } } } }, "/add_document": { "post": { "tags": [ "Documents" ], "summary": "Add document(s) to agent", "description": "Add one or more documents to an agent's vector DB. Expects 'documents' array and matching 'ids' array of equal length.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "documents_added" } } } } } }, "x-when-to-use": "Call this to seed an agent's knowledge base. Documents are chunked, embedded, and stored in vector storage for semantic retrieval. Do this before agent_chat to give the agent access to your content.", "x-use-cases": [ "Uploading a product knowledge base to back a support bot", "Feeding legal documents to a contract-analysis agent", "Adding FAQs so the agent can answer common questions precisely", "Syncing content updates when your source documents change" ], "x-notes": "The documents array and ids array must be the same length. IDs must be unique within the agent \u2014 use deterministic IDs (e.g. a filename hash) so you can update documents by ID later. Large documents are automatically chunked.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "documents": { "type": "array", "example": [ "string" ] }, "ids": { "type": "array", "example": [ "string" ] }, "metadata": { "type": "object", "example": {} } } } } } } } }, "/search_documents": { "post": { "tags": [ "Documents" ], "summary": "Search agent documents", "description": "Perform a vector/semantic search against an agent's document collection. Provide 'query' and optional 'top_k'.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "results": [] } } } } } }, "x-when-to-use": "Use when you need to retrieve specific document chunks by semantic similarity \u2014 useful for building a custom RAG pipeline or debugging what context the agent can see for a given query.", "x-use-cases": [ "Building a custom RAG pipeline outside of agent_chat", "Debugging why the agent answered incorrectly by inspecting which chunks were retrieved", "Adding a 'search your knowledge base' feature to your UI", "Pre-fetching context before constructing a custom LLM prompt" ], "x-notes": "top_k defaults to 5. Increasing it improves recall but may add noise. Results are ordered by cosine similarity score (highest first). This endpoint does NOT run LLM inference \u2014 it only returns matching document chunks.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "query": { "type": "string", "example": "string" }, "top_k": { "type": "string", "example": 5 } } } } } } } }, "/update_document": { "post": { "tags": [ "Documents" ], "summary": "Update existing document(s)", "description": "Update documents in an agent's vector DB by document id(s). Provide 'document_ids' and 'new_docs' fields.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "document_updated" } } } } } }, "x-when-to-use": "Call this to replace the content of existing documents in an agent's vector store while keeping the same document IDs.", "x-use-cases": [ "Updating a FAQ document after policy changes", "Refreshing product documentation when a new version ships", "Correcting inaccurate content that the agent has been using in responses", "Syncing documents periodically from an external CMS" ], "x-notes": "document_ids and new_docs arrays must have the same length. The old embeddings are replaced \u2014 this is an upsert by ID. If a document_id does not exist, some implementations will insert it as new.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "document_ids": { "type": "array", "example": [ "string" ] }, "new_docs": { "type": "array", "example": [ "string" ] }, "metadata": { "type": "object", "example": {} } } } } } } } }, "/update_document_metadata": { "post": { "tags": [ "Documents" ], "summary": "Update document metadata", "description": "Update only the metadata for a given document id in an agent's vector DB.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "document_metadata_updated" } } } } } }, "x-when-to-use": "Call this to change metadata (tags, source, category) on a document without re-embedding its content.", "x-use-cases": [ "Tagging documents with a new category for filtered retrieval", "Updating the source URL after a content migration", "Adding version or last-modified timestamps to track freshness" ], "x-notes": "Only metadata is changed \u2014 the document text and its vector embedding remain untouched. This is cheaper and faster than a full document update when only labels need to change.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "document_id": { "type": "string", "example": "string" }, "metadata": { "type": "object", "example": {} } } } } } } } }, "/create_memory": { "post": { "tags": [ "Memory" ], "summary": "Initialize memory system", "description": "Create/initialize a SimpleMem memory system for an agent. This creates a ChromaDB collection for storing memory entries. Set 'clear_db' to true to clear existing memories.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "memory_system_initialized", "agent_id": "string", "cleared": false } } } } } }, "x-when-to-use": "Call once before using any other /memory endpoints for a given agent. This initialises the ChromaDB collection that stores structured memory entries. If the collection already exists it is a no-op unless clear_db is true.", "x-use-cases": [ "First-time setup: call immediately after creating a new agent", "Resetting an agent's memory during development or testing with clear_db: true", "Re-initialising after a database migration or storage reset" ], "x-notes": "This must be called before add_memory, read_memory, or get_context \u2014 those endpoints will fail if the memory system has not been initialised first. Setting clear_db: true permanently erases all stored memories for that agent.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "clear_db": { "type": "boolean", "example": false } } } } } } } }, "/add_memory": { "post": { "tags": [ "Memory" ], "summary": "Direct memory save (no LLM)", "description": "Directly save pre-structured memory entries without LLM processing. Use this when you already have structured memory data (lossless_restatement, keywords, etc.) and want to bypass the LLM extraction step.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "memories_added", "agent_id": "string", "entries_added": 0, "entry_ids": [] } } } } } }, "x-when-to-use": "Use to store structured facts directly in the agent's memory, bypassing LLM extraction. Prefer process_raw when you have raw conversation transcripts to process.", "x-use-cases": [ "Storing a user's explicitly stated preference (e.g. 'I prefer Python over JavaScript')", "Saving structured facts from a form submission or structured event", "Persisting key decisions made in a conversation for future sessions", "Building up a user profile incrementally from explicit data" ], "x-notes": "Unlike process_raw, this bypasses LLM processing \u2014 the memory is stored exactly as you provide it. Supply meaningful keywords to improve future recall accuracy. The lossless_restatement field should be a complete, self-contained statement.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "memories": { "type": "array", "example": [ { "lossless_restatement": "string", "keywords": [ "string" ], "timestamp": "ISO8601 (optional)", "location": "string (optional)", "persons": [ "string" ], "entities": [ "string" ], "topic": "string (optional)" } ] } } } } } } } }, "/get_context": { "post": { "tags": [ "Memory" ], "summary": "Q&A with memory context", "description": "Ask a question and get an LLM-generated answer using memory context. Full Q&A flow: Query \u2192 HybridRetrieval \u2192 AnswerGenerator \u2192 Response. Returns both the answer and the memory contexts used.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "question": "string", "answer": "string", "contexts_used": [ { "entry_id": "string", "lossless_restatement": "string", "topic": "string" } ] } } } } } }, "x-when-to-use": "Call when you need an LLM-generated answer grounded in the agent's stored memories. It handles the full retrieval-augmented generation cycle internally \u2014 use it when you want answers, not raw chunks.", "x-use-cases": [ "Answering 'what did we discuss last time?' from a user's perspective", "Showing users what the agent remembers about a specific topic", "Building a memory-backed Q&A interface without a custom RAG pipeline", "Summarising past interactions or decisions on a given subject" ], "x-notes": "agent_chat already calls this internally \u2014 only use get_context if you are building a custom pipeline and want the answer + source contexts separately. The contexts_used array shows exactly which memories were retrieved, useful for debugging or citations.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "question": { "type": "string", "example": "string" } } } } } } } }, "/read_memory": { "post": { "tags": [ "Memory" ], "summary": "Hybrid search retrieval", "description": "Search memories using hybrid retrieval combining semantic (vector similarity), keyword (BM25-style), and structured (metadata filtering) search. Optionally enable reflection for multi-round retrieval.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "query": "string", "results_count": 0, "results": [ { "entry_id": "string", "lossless_restatement": "string", "keywords": [], "timestamp": "string", "location": "string", "persons": [], "entities": [], "topic": "string" } ] } } } } } }, "x-when-to-use": "Call this to search an agent's memory using hybrid retrieval (semantic + keyword + metadata). Use it when you need raw memory results without an LLM-generated answer.", "x-use-cases": [ "Building a custom RAG pipeline where you supply your own answer generation", "Debugging memory retrieval quality by inspecting raw results", "Showing users a list of related memories in a UI", "Pre-filtering memories before passing them to a specialized prompt" ], "x-notes": "Combines vector similarity, keyword matching, and metadata filtering. Set enable_reflection to true for multi-round retrieval that refines results (slower but higher recall). top_k defaults to 5.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "query": { "type": "string", "example": "string" }, "top_k": { "type": "string", "example": 5 }, "enable_reflection": { "type": "boolean", "example": false } } } } } } } }, "/process_raw": { "post": { "tags": [ "Memory" ], "summary": "Process dialogues via LLM", "description": "Process raw dialogues through LLM to extract structured memory entries. Flow: ADD_DIALOGUE \u2192 LLM \u2192 JSON RESPONSE \u2192 N Memory units \u2192 Vector Store. Each dialogue is processed to extract facts, entities, timestamps, and keywords.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "dialogues_processed", "agent_id": "string", "dialogues_processed": 0 } } } } } }, "x-when-to-use": "Call this when you have raw conversation transcripts or dialogue logs and want the LLM to automatically extract structured memory entries (facts, entities, timestamps) from them.", "x-use-cases": [ "Ingesting chat logs from a customer support platform into agent memory", "Processing meeting transcripts to extract action items and decisions", "Converting unstructured interview notes into searchable memory entries", "Archiving conversation history from another system into structured memory" ], "x-notes": "This endpoint triggers LLM inference and may take 10-120 seconds depending on dialogue volume. Each dialogue is processed independently. Use add_memory instead if you already have structured data to avoid unnecessary LLM costs.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "dialogues": { "type": "array", "example": [ { "speaker": "string", "content": "string", "timestamp": "ISO8601 string (optional)" } ] } } } } } } } }, "/update_memory": { "post": { "tags": [ "Memory" ], "summary": "Update memory entry", "description": "Update an existing memory entry in ChromaDB. You can update the lossless_restatement (document content) and/or metadata fields (timestamp, location, persons, entities, topic, keywords).", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "memory_updated", "agent_id": "string", "entry_id": "string" } } } } } }, "x-when-to-use": "Call this to correct or enrich an existing memory entry \u2014 for example, updating a fact that has changed or adding missing metadata like location or persons.", "x-use-cases": [ "Correcting a memory entry that contains outdated information", "Adding a person's name to a memory after learning who was involved", "Updating a timestamp when a scheduled event is rescheduled", "Enriching a memory with additional keywords to improve future retrieval" ], "x-notes": "Only include fields you want to change in the updates object. If you update lossless_restatement, the vector embedding is also re-computed. Metadata-only updates are faster since they skip re-embedding.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "entry_id": { "type": "string", "example": "string" }, "updates": { "type": "object", "example": { "lossless_restatement": "string (optional)", "timestamp": "string (optional)", "location": "string (optional)", "persons": [ "string" ], "entities": [ "string" ], "topic": "string (optional)", "keywords": [ "string" ] } } } } } } } } }, "/delete_memory": { "post": { "tags": [ "Memory" ], "summary": "Delete memory entries", "description": "Delete one or more memory entries from ChromaDB by their entry IDs. This permanently removes the memory entries from the agent's vector store.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "message": "memories_deleted", "agent_id": "string", "deleted_count": 0, "entry_ids": [] } } } } } }, "x-when-to-use": "Call this to permanently remove specific memory entries by their IDs. Use for GDPR erasure, correcting bad data, or cleaning up test entries.", "x-use-cases": [ "Honoring a user's right-to-be-forgotten request by deleting specific memories", "Removing incorrect or hallucinated memory entries", "Cleaning up test data from development sessions", "Purging sensitive information that was accidentally stored" ], "x-notes": "This action is irreversible \u2014 deleted memories cannot be recovered. Pass one or more entry_ids. Use list_memories or read_memory first to identify which IDs to delete.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "entry_ids": { "type": "array", "example": [ "string" ] } } } } } } } }, "/agent_stats": { "post": { "tags": [ "Analytics & Stats" ], "summary": "Get agent statistics", "description": "Get comprehensive statistics for an agent including total memories, documents, topic breakdown, unique persons/locations mentioned, and activity metadata.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "agent_name": "string", "agent_status": "string", "statistics": { "total_memories": 0, "total_documents": 0, "topics": {}, "unique_persons": [], "unique_locations": [], "persons_count": 0, "locations_count": 0 }, "created_at": "string", "updated_at": "string" } } } } } }, "x-when-to-use": "Call this to get a comprehensive overview of an agent's data \u2014 how many memories and documents it has, topic distribution, and activity timestamps.", "x-use-cases": [ "Displaying an agent health dashboard in an admin panel", "Monitoring memory growth over time for capacity planning", "Auditing which topics and persons an agent knows about", "Verifying that data ingestion pipelines are working correctly" ], "x-notes": "Statistics are computed on-demand and may be slightly delayed for very large collections. The topics breakdown shows unique topics and their frequency across all memories.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" } } } } } } } }, "/api_usage": { "post": { "tags": [ "Analytics & Stats" ], "summary": "Get API usage statistics", "description": "Get API usage statistics for the authenticated user including total API calls, calls by endpoint, rate limit status, agents count, and billing period information.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "user_id": "string", "billing_period": { "start": "string", "end": "string" }, "agents": { "total": 0, "active": 0, "disabled": 0 }, "api_calls": { "total": 0, "by_endpoint": {}, "limit": 10000, "remaining": 10000 }, "memory_storage": { "total_memories": 0, "storage_mb": 0, "limit_mb": 1000 }, "rate_limits": { "requests_per_minute": 60, "requests_per_day": 10000 } } } } } } }, "x-when-to-use": "Call this to check your account's API consumption, rate limit status, and remaining quota within the current billing period.", "x-use-cases": [ "Displaying a usage meter in your application's billing page", "Alerting when approaching rate limits or quota caps", "Generating monthly usage reports for internal accounting", "Debugging 429 errors by checking remaining request allowance" ], "x-notes": "Authenticated by API key \u2014 returns usage for the key's associated account. Counters reset at the start of each billing period. The rate_limits object shows your current plan's limits." } }, "/health_detailed": { "get": { "tags": [ "Analytics & Stats" ], "summary": "Detailed health check", "description": "Get detailed health status of all backend services including database connectivity, vector store status, and LLM service status. Returns 503 if any critical service is unhealthy.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "timestamp": "string", "version": "2.0.0", "services": { "database": { "status": "healthy", "type": "supabase" }, "vector_store": { "status": "healthy", "type": "chromadb" }, "llm": { "status": "healthy", "provider": "openai" } } } } } } } }, "x-when-to-use": "Call this to verify that all backend services (database, vector store, LLM) are operational before routing traffic or as part of automated monitoring.", "x-use-cases": [ "Automated health checks from an uptime monitoring service", "Pre-flight validation before running a batch data import", "Diagnosing which subsystem is causing failures", "Load balancer health probes to route away from unhealthy instances" ], "x-notes": "Returns HTTP 200 if all services are healthy, 503 if any critical service is degraded. No authentication required \u2014 safe to expose to monitoring tools. Check individual service statuses in the response body." } }, "/list_memories": { "post": { "tags": [ "Bulk Operations" ], "summary": "List all memories (paginated)", "description": "List all memories for an agent with pagination support. Supports filtering by topic or person. Returns metadata for each memory entry.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "total_count": 0, "limit": 50, "offset": 0, "has_more": false, "memories": [] } } } } } }, "x-when-to-use": "Call this to paginate through all memory entries for an agent, optionally filtering by topic or person. Use for bulk inspection or export workflows.", "x-use-cases": [ "Building a memory browser UI with pagination", "Auditing all memories stored for a specific person (GDPR subject access request)", "Finding memory entries on a specific topic for review or deletion", "Iterating through all memories for a custom export or transformation pipeline" ], "x-notes": "Use limit and offset for pagination. Filter by filter_topic or filter_person to narrow results. Returns metadata for each entry including entry_id, which you can use with update_memory or delete_memory.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "limit": { "type": "string", "example": 50 }, "offset": { "type": "string", "example": 0 }, "filter_topic": { "type": "string", "example": "string (optional)" }, "filter_person": { "type": "string", "example": "string (optional)" } } } } } } } }, "/bulk_add_memory": { "post": { "tags": [ "Bulk Operations" ], "summary": "Bulk add memories", "description": "Add multiple memories in a single request (max 100). Optimized for high-volume memory ingestion. Returns individual success/error status for each memory.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "memories_added": 0, "memories_skipped": 0, "entry_ids": [], "errors": null } } } } } }, "x-when-to-use": "Call this when you need to ingest many pre-structured memories at once (up to 100 per request). More efficient than calling /add_memory repeatedly in a loop.", "x-use-cases": [ "Initial data migration from another system into agent memory", "Batch-loading user preferences collected from a form or survey", "Restoring memories from a backup without using /import_memories", "Programmatically seeding an agent with a knowledge base of structured facts" ], "x-notes": "Maximum 100 memories per request. Set skip_duplicates to true to avoid reinserting memories that already exist (matched by lossless_restatement). Returns per-entry status so you can identify and retry failures.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "memories": { "type": "array", "example": [ { "lossless_restatement": "string", "keywords": [ "string" ], "timestamp": "string (optional)", "location": "string (optional)", "persons": [ "string" ], "entities": [ "string" ], "topic": "string (optional)" } ] }, "skip_duplicates": { "type": "boolean", "example": false } } } } } } } }, "/export_memories": { "post": { "tags": [ "Data Portability" ], "summary": "Export all memories", "description": "Export all memories for an agent as JSON for backup, migration, or analysis. Returns a complete backup that can be imported to another agent or restored later.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "export": { "version": "1.0", "export_timestamp": "string", "agent_id": "string", "agent_name": "string", "total_memories": 0, "memories": [] } } } } } } }, "x-when-to-use": "Call this to create a full JSON backup of all memories for an agent. Use for data portability, migration between environments, or offline analysis.", "x-use-cases": [ "Creating a backup before running destructive operations", "Migrating an agent's memory from staging to production", "Providing a data export for GDPR data portability requests", "Downloading memories for offline analysis or reporting" ], "x-notes": "The export includes all memory entries with their full metadata. Large exports may take time \u2014 use a generous timeout. The returned format is compatible with /import_memories for restoration.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "format": { "type": "string", "example": "json" } } } } } } } }, "/import_memories": { "post": { "tags": [ "Data Portability" ], "summary": "Import memories from backup", "description": "Import memories from a previously exported JSON backup. Supports 'append' mode to add to existing memories or 'replace' mode to clear existing memories first.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "merge_mode": "append", "memories_imported": 0, "source_agent": "string", "source_timestamp": "string", "entry_ids": [], "errors": null } } } } } }, "x-when-to-use": "Call this to restore memories from a previous export or migrate memories from one agent to another. Supports append (additive) or replace (destructive) modes.", "x-use-cases": [ "Restoring memories from a backup after accidental deletion", "Cloning an agent's memory to a new agent in a different environment", "Merging memories from a decommissioned agent into an active one", "Seeding a new agent with memories exported from a template agent" ], "x-notes": "Use merge_mode \"append\" to add without affecting existing memories, or \"replace\" to clear and reimport. The export_data format must match what /export_memories produces. Large imports may take significant time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "export_data": { "type": "object", "example": { "version": "1.0", "memories": [] } }, "merge_mode": { "type": "string", "example": "append" } } } } } } } }, "/memory_summary": { "post": { "tags": [ "Data Portability" ], "summary": "AI memory summary", "description": "Generate an AI-powered summary of all agent memories. Optionally focus on a specific topic. Returns summary along with metadata about topics and persons mentioned.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "ok": true, "agent_id": "string", "summary": "string", "memory_count": 0, "topics_covered": [], "persons_mentioned": [], "focus_topic": null, "summary_length": "medium" } } } } } }, "x-when-to-use": "Call this to get an AI-generated natural language summary of everything an agent remembers, optionally focused on a specific topic.", "x-use-cases": [ "Showing a user a digest of what the agent knows about them", "Generating a briefing document from an agent's accumulated knowledge", "Summarising a project's history from stored memories before a meeting", "Creating a topic-focused report from an agent's memory" ], "x-notes": "This triggers LLM inference and may take 10-60 seconds. summary_length accepts \"brief\", \"medium\", or \"detailed\". Use focus_topic to narrow the summary to a specific subject. Useful for human review of agent knowledge.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "agent_id": { "type": "string", "example": "string" }, "focus_topic": { "type": "string", "example": "string (optional)" }, "summary_length": { "type": "string", "example": "medium" } } } } } } } }, "/memory": { "get": { "tags": [ "API Test Examples" ], "summary": "Memory page (UI)", "description": "Returns the memory page (may redirect for unauthenticated users).", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "html": "string" } } } } } }, "x-when-to-use": "Use this endpoint to load the memory management UI page in a browser. It renders the interactive memory interface for the authenticated user.", "x-use-cases": [ "Navigating to the memory page in a web application", "Testing that the memory UI renders correctly after deployment", "Embedding the memory page in an iframe within a larger admin tool" ], "x-notes": "Returns HTML, not JSON. Unauthenticated requests may be redirected to a login page. This is a UI endpoint, not an API endpoint \u2014 use /read_memory or /list_memories for programmatic access." } }, "/web/get_sessions": { "get": { "tags": [ "API Test Examples" ], "summary": "Get sessions (API)", "description": "GET sessions by id query parameter. Returns JSON list or object.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "sessions": [] } } } } } }, "x-when-to-use": "Call this to retrieve chat session metadata by session ID. Use it to look up session details or verify a session exists before sending messages.", "x-use-cases": [ "Loading a previous chat session to display its history", "Verifying that a session ID is valid before calling /web/chat", "Listing all sessions for a user in a session picker UI" ], "x-notes": "Pass the session id as a query parameter. Returns session metadata including creation time and associated user. If no id is provided, may return all sessions for the authenticated user.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "example": "uuid (query)" } ] } }, "/web/rag": { "post": { "tags": [ "API Test Examples" ], "summary": "RAG search", "description": "Run a RAG-style search (POST JSON).", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "results": [] } } } } } }, "x-when-to-use": "Call this to perform a RAG-style semantic search against a user's stored data. Returns ranked document chunks without generating an LLM answer.", "x-use-cases": [ "Powering a search bar in the web UI with semantic results", "Fetching relevant context before constructing a custom prompt", "Debugging retrieval quality by inspecting raw search results", "Building a citation list showing which stored content matches a query" ], "x-notes": "Unlike /get_context, this does not generate an LLM answer \u2014 it only retrieves matching chunks. top_k controls how many results to return (default 3). Results are ranked by relevance score.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "example": "string" }, "query": { "type": "string", "example": "string" }, "top_k": { "type": "string", "example": 3 } } } } } } } }, "/validate_key": { "post": { "tags": [ "API Test Examples" ], "summary": "Validate API key", "description": "Validate API key. POST JSON {api_key: string}. Returns {valid: bool}.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "valid": true } } } } } }, "x-when-to-use": "Call this to check whether an API key is valid and active before using it in subsequent requests. Useful for key verification flows in onboarding or settings pages.", "x-use-cases": [ "Validating a user-entered API key in a settings form before saving", "Checking key validity during application startup", "Implementing a key rotation workflow that verifies the new key works" ], "x-notes": "Returns {valid: true} if the key is active and has not been revoked. Does not reveal which permissions the key has \u2014 only that it is recognized. Use this as a lightweight pre-check rather than making a full API call.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "example": "string" } } } } } } } }, "/web/create_session": { "post": { "tags": [ "API Test Examples" ], "summary": "Create chat session", "description": "Create a new chat session. Returns thread_id.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "thread_id": "string" } } } } } }, "x-when-to-use": "Call this to initialize a new chat session for a user. The returned thread_id is required by /web/chat to send messages within that session.", "x-use-cases": [ "Starting a new conversation thread when a user clicks \"New Chat\"", "Creating a session programmatically for automated testing", "Initializing a support conversation from an external trigger (e.g., email or webhook)" ], "x-notes": "Store the returned thread_id \u2014 it is required for all subsequent /web/chat calls in this conversation. Each session maintains its own message history independently.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "string", "example": "string" } } } } } } } }, "/web/chat": { "post": { "tags": [ "API Test Examples" ], "summary": "Send chat message (streaming)", "description": "Send a chat message to the streaming chat endpoint. Example shows a simple non-streaming POST consumer.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "reply": "string / stream" } } } } } }, "x-when-to-use": "Call this to send a user message and receive an AI response within an established chat session. Supports streaming responses for real-time display.", "x-use-cases": [ "Powering the main chat interface in a web application", "Sending follow-up messages in an ongoing conversation thread", "Building a chatbot widget that streams responses token-by-token", "Automating multi-turn conversations for testing or scripting" ], "x-notes": "Requires a valid thread_id from /web/create_session. The history array is optional \u2014 the server maintains history server-side, but you can pass it for context if needed. Response may be streamed (text/event-stream) depending on client headers.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "thread_id": { "type": "string", "example": "string" }, "user_id": { "type": "string", "example": "string" }, "message": { "type": "string", "example": "string" }, "history": { "type": "array", "example": [] } } } } } } } }, "/ping": { "get": { "tags": [ "API Test Examples" ], "summary": "Ping server", "description": "Simple health check for the running server.", "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "example": { "status": "string" } } } } } }, "x-when-to-use": "Call this as a lightweight connectivity check to verify the server is running and reachable. Does not require authentication.", "x-use-cases": [ "Health check probes from a load balancer or container orchestrator", "Client-side connectivity test before making authenticated API calls", "Automated monitoring to detect service outages" ], "x-notes": "This is the simplest endpoint \u2014 no auth required, minimal processing. Returns a status string. Use /health_detailed if you need to verify individual backend service health." } } } }