Pocket Agent — Public REST API V1 API

{"openapi":"3.1.0","info":{"title":"Pocket Agent — Public REST API","version":"1.0.0","description":"PA is your brain. Bring any agent. This API exposes your brain files, memory tiers, personas, and privacy zones to any client that speaks REST. Authenticate with a `pa_live_` API key as a Bearer token. Every brain-reading endpoint enforces your Privacy zones (ContainmentGuard)."},"servers":[{"url":"https://aipocketagent.com/api/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"pa_live_<key>","description":"Generate a key in Settings → API keys. Pass as `Authorization: Bearer pa_live_…`."}}},"paths":{"/brain/tree":{"get":{"summary":"List brain files + folders","description":"Privacy-zone filtered — private-zone files are omitted.","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"The brain tree.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tree":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"type":{"type":"string","enum":["blob","tree"]}},"required":["path","type"],"additionalProperties":false}},"blockedCount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["tree","blockedCount"],"additionalProperties":false}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"No brain repo connected.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/brain/file":{"get":{"summary":"Read a brain file","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"path","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file content.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string"},"content":{"type":"string"}},"required":["path","content"],"additionalProperties":false}}}},"403":{"description":"Path is in a private zone.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"File not found.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Invalid path.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}},"post":{"summary":"Write a brain file","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string","minLength":1,"maxLength":400},"content":{"type":"string","maxLength":1000000},"mode":{"default":"replace","type":"string","enum":["append","replace"]},"commitMessage":{"type":"string","maxLength":200}},"required":["path","content","mode"],"additionalProperties":false}}}},"responses":{"200":{"description":"Committed.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string"},"sha":{"type":"string"},"committed":{"type":"boolean","const":true}},"required":["path","sha","committed"],"additionalProperties":false}}}},"403":{"description":"Path is in a private zone.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"No write token.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Invalid body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/memory/tier":{"get":{"summary":"List memory entries in a tier","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"tier","in":"query","required":true,"schema":{"type":"string","enum":["work","knowledge","patterns"]}}],"responses":{"200":{"description":"Entries in the tier.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"tier":{"type":"string","enum":["work","knowledge","patterns"]},"entries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"path":{"type":"string"}},"required":["name","path"],"additionalProperties":false}}},"required":["tier","entries"],"additionalProperties":false}}}},"422":{"description":"Invalid tier.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/memory/entry":{"post":{"summary":"Write a memory entry","description":"Tier is taken from the body when present, else auto-classified.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"content":{"type":"string","minLength":1,"maxLength":200000},"tier":{"type":"string","enum":["work","knowledge","patterns"]}},"required":["name","content"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"path":{"type":"string"},"tier":{"type":"string","enum":["work","knowledge","patterns"]},"sha":{"type":"string"},"classifiedReason":{"type":"string"}},"required":["path","tier","sha","classifiedReason"],"additionalProperties":false}}}},"409":{"description":"No write token.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"422":{"description":"Invalid body.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/personas":{"get":{"summary":"List your personas","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Your personas.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"personas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"type":"string"},"slug":{"type":"string"},"mode":{"type":"string"},"status":{"type":"string"}},"required":["id","name","slug","mode","status"],"additionalProperties":false}}},"required":["personas"],"additionalProperties":false}}}}}}},"/personas/{id}/invoke":{"post":{"summary":"Invoke a persona (streams)","description":"Streams a Server-Sent Events response (`data: {json}` lines: meta, delta, done, error). ContainmentGuard is scoped to the persona's knowledge zone.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"message":{"type":"string","minLength":1,"maxLength":8000},"conversationId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["message"],"additionalProperties":false}}}},"responses":{"200":{"description":"An SSE stream of the persona response."},"404":{"description":"Persona not found.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"409":{"description":"Persona not active.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"429":{"description":"Persona monthly cap or rate limit reached.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}},"/zones":{"get":{"summary":"List your privacy zones","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Your privacy zones.","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"zones":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"patterns":{"type":"array","items":{"type":"string"}},"private":{"type":"boolean"}},"required":["name","patterns","private"],"additionalProperties":false}},"isDefault":{"type":"boolean"}},"required":["zones","isDefault"],"additionalProperties":false}}}}}}}}}