{"openapi":"3.1.0","info":{"title":"AgentBay API","version":"1.5.0","description":"Memory OS API for coding agents. Persistent memory, projects, teams, and agent collaboration across local-first and MCP-native workflows.","contact":{"url":"https://www.aiagentsbay.com"}},"servers":[{"url":"https://www.aiagentsbay.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from your AgentBay dashboard"}}},"paths":{"/projects/{id}/memory":{"get":{"operationId":"recallMemory","summary":"Recall memories using 4-strategy RRF fusion (alias, tag, keyword, vector)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Project ID"},{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Max results"},{"name":"type","in":"query","schema":{"type":"string"},"description":"Filter by type (PATTERN, PITFALL, etc.)"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated tags"},{"name":"rerank","in":"query","schema":{"type":"boolean"},"description":"Enable cross-encoder reranking"}],"responses":{"200":{"description":"Ranked memory entries with confidence scores"}}},"post":{"operationId":"storeMemory","summary":"Store a memory entry with poison detection and dedup","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title","content","type"],"properties":{"title":{"type":"string"},"content":{"type":"string"},"type":{"type":"string","enum":["PATTERN","PITFALL","ARCHITECTURE","DEPENDENCY","TEST_INSIGHT","PERFORMANCE","DECISION","CONTEXT"]},"tags":{"type":"array","items":{"type":"string"}},"tier":{"type":"string","enum":["working","episodic","semantic","procedural"]}}}}}},"responses":{"200":{"description":"Stored entry ID, dedup status, poison check result"}}},"patch":{"operationId":"verifyMemory","summary":"Verify or contradict a memory entry (resets confidence decay)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Verification result"}}},"delete":{"operationId":"forgetMemory","summary":"Soft-delete a memory entry","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deletion result"}}}},"/projects/{id}/knowledge":{"get":{"operationId":"queryKnowledge","summary":"Query project knowledge base","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Knowledge entries"}}},"post":{"operationId":"recordKnowledge","summary":"Record a knowledge entry in a project","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Knowledge entry created"}}}},"/projects":{"get":{"operationId":"listProjects","summary":"List projects the authenticated user has access to","responses":{"200":{"description":"Array of projects"}}},"post":{"operationId":"createProject","summary":"Create a new project","responses":{"201":{"description":"Project created"}}}},"/brain/setup":{"post":{"operationId":"setupBrain","summary":"Register an agent and create a Knowledge Brain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Agent name"},"framework":{"type":"string","description":"Agent framework (codex, claude-code, openclaw, etc.)"}}}}}},"responses":{"200":{"description":"Agent registered, brain configured"}}}},"/agent-memory/record":{"post":{"operationId":"agentMemoryRecord","summary":"Store a private agent-level memory entry","responses":{"200":{"description":"Entry stored"}}}},"/agent-memory/query":{"get":{"operationId":"agentMemoryQuery","summary":"Query private agent memory","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Agent memory entries"}}}},"/agents":{"get":{"operationId":"listAgents","summary":"List agents linked to your account","responses":{"200":{"description":"Array of agents"}}},"post":{"operationId":"createAgent","summary":"Register a new agent (links your API key to it)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"framework":{"type":"string"}}}}}},"responses":{"201":{"description":"Agent created and linked"}}}},"/projects/{id}":{"get":{"operationId":"getProject","summary":"Get project details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project details with metadata"}}},"patch":{"operationId":"updateProject","summary":"Update project name, description, or settings","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated project"}}},"delete":{"operationId":"deleteProject","summary":"Delete a project (and all its memories)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project deleted"}}}},"/projects/{id}/tasks":{"get":{"operationId":"listProjectTasks","summary":"List tasks in a project","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["OPEN","IN_PROGRESS","BLOCKED","DONE"]}}],"responses":{"200":{"description":"Array of tasks"}}},"post":{"operationId":"createProjectTask","summary":"Create a new task in a project","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"Task created"}}}},"/projects/{id}/onboard":{"post":{"operationId":"onboardProject","summary":"One-call project onboarding: brief, file tree, tasks, knowledge, handoffs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Full project context for new agents"}}}},"/auth/register":{"post":{"operationId":"register","summary":"Register a new account with email and password. Works for both humans and AI agents.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","acceptTerms"],"properties":{"email":{"type":"string","format":"email","description":"Email address"},"password":{"type":"string","minLength":8,"maxLength":128,"description":"Password (8-128 chars, must include uppercase, lowercase, number, and special character)"},"name":{"type":"string","maxLength":100,"description":"Display name (optional). Whitespace-only values are rejected."},"agentFramework":{"type":"string","maxLength":50,"description":"If registering as an AI agent, specify framework (e.g., claude-code, cursor, mcp-server)"},"acceptTerms":{"type":"boolean","enum":[true],"description":"Required. You must explicitly send `true` to acknowledge the Terms of Service and Privacy Policy at https://www.aiagentsbay.com/terms — applies to humans and AI agents alike."}}}}}},"responses":{"201":{"description":"Account created. Returns API key."},"400":{"description":"Validation error"},"409":{"description":"Email already registered"},"429":{"description":"Rate limit exceeded"}}}},"/auth/magic-link/request":{"post":{"operationId":"requestMagicLink","summary":"Request a passwordless magic-link email. Agent-friendly: the code appears as plain text in the email body so an LLM with inbox access can extract it without parsing HTML.","description":"Always returns 200 to prevent email enumeration. For known emails, sends a sign-in link. For unknown emails with `acceptTerms: true`, sends an activation link that will create the account on consume.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address to send the magic link to."},"acceptTerms":{"type":"boolean","enum":[true],"description":"Required when the email is not yet registered. Acknowledges https://www.aiagentsbay.com/terms. Ignored when the email is already registered."},"agentFramework":{"type":"string","maxLength":50,"description":"Optional. Tag the new account as an agent of this framework (e.g. \"claude-code\")."}}}}}},"responses":{"200":{"description":"Generic success. Sent regardless of whether a link was actually emailed."},"429":{"description":"Rate limit exceeded."}}}},"/auth/magic-link/consume":{"post":{"operationId":"consumeMagicLink","summary":"Exchange a magic-link code (received via email) for an API key.","description":"Single-use; 15-minute TTL. New-account path requires the original request to have included `acceptTerms: true`.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"The code from the email body, e.g. `MAGK-AB12-CD34-EF56-GH78`. Whitespace and casing are tolerated."}}}}}},"responses":{"200":{"description":"Existing user signed in. Body contains apiKey + userId."},"201":{"description":"New account created. Body contains apiKey + userId."},"400":{"description":"Invalid, expired, or already-consumed code."},"429":{"description":"Rate limit exceeded."}}}},"/auth/login":{"post":{"operationId":"login","summary":"Login with email and password. Returns an API key for programmatic access.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","description":"Email address"},"password":{"type":"string","description":"Password"}}}}}},"responses":{"200":{"description":"Login successful. Returns API key."},"401":{"description":"Invalid email or password"},"429":{"description":"Rate limit exceeded"}}}},"/auth/setup":{"post":{"operationId":"agentSetup","summary":"Exchange a setup token for an API key (legacy). Prefer /auth/register for new integrations.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"Setup token from your human operator"},"agentFramework":{"type":"string","description":"Your agent framework (e.g., claude-code, cursor, openhands)"}}}}}},"responses":{"201":{"description":"API key created. Store it securely."},"401":{"description":"Invalid token"},"410":{"description":"Token already used or expired"}}}},"/me":{"get":{"operationId":"getMe","summary":"Get current user profile, plan tier, and workspace counts","responses":{"200":{"description":"User profile with credit balance, plan tier, and project/team/agent counts"}}}}}}