{"openapi":"3.1.0","info":{"title":"PersonaMesh API","version":"0.3.0","description":"Persona AI agents — author, train, run, and audit. See https://personamesh.ai/docs.","contact":{"email":"support@personamesh.ai","url":"https://personamesh.ai/contact"},"license":{"name":"Apache-2.0","url":"https://www.apache.org/licenses/LICENSE-2.0"}},"servers":[{"url":"https://api.personamesh.ai","description":"Production"},{"url":"{public_url}/api","description":"Self-hosted / on-prem / single-URL gateway","variables":{"public_url":{"default":"http://localhost:8080"}}}],"security":[{"bearerAuth":[]},{"sessionCookie":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"pmesh_…"},"sessionCookie":{"type":"apiKey","in":"cookie","name":"pmesh_session"}},"parameters":{"personaId":{"name":"persona_id","in":"path","required":true,"schema":{"type":"string"}},"conversationId":{"name":"id","in":"path","required":true,"schema":{"type":"string"}},"idempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Client-supplied key; replaying with the same key returns the cached response."}},"schemas":{"ErrorEnvelope":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}},"Persona":{"type":"object","required":["id","name","version","personality"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"version":{"type":"integer","minimum":1},"identity":{"type":"object","properties":{"pronouns":{"type":"string"},"location":{"type":"string"},"timezone":{"type":"string"},"backstory":{"type":"string"}}},"expertise":{"type":"array","items":{"type":"object","required":["domain","level"],"properties":{"domain":{"type":"string"},"level":{"type":"string","enum":["novice","competent","proficient","expert","world-class"]},"sources":{"type":"array","items":{"type":"string"}}}}},"personality":{"type":"object","required":["big_five"],"properties":{"big_five":{"type":"object","required":["O","C","E","A","N"],"properties":{"O":{"type":"number","minimum":0,"maximum":1},"C":{"type":"number","minimum":0,"maximum":1},"E":{"type":"number","minimum":0,"maximum":1},"A":{"type":"number","minimum":0,"maximum":1},"N":{"type":"number","minimum":0,"maximum":1}}},"values":{"type":"array","items":{"type":"string"}},"quirks":{"type":"array","items":{"type":"string"}}}},"voice":{"type":"object"},"memory_policy":{"type":"object"},"tools":{"type":"object"},"safety":{"type":"object"},"frozen_at":{"type":"string","format":"date-time","description":"If set, the persona is frozen — chat + autonomy return 423."}}},"ChatReply":{"type":"object","required":["conversation_id","reply","fingerprint","tokens_in","tokens_out","cost_usd","model"],"properties":{"conversation_id":{"type":"string"},"reply":{"type":"string"},"fingerprint":{"type":"string"},"tokens_in":{"type":"integer"},"tokens_out":{"type":"integer"},"cost_usd":{"type":"number"},"model":{"type":"string"},"recalled_memory_ids":{"type":"array","items":{"type":"string"}},"knowledge_citations":{"type":"array","items":{"type":"object","properties":{"doc_id":{"type":"string"},"document_title":{"type":"string"},"ordinal":{"type":"integer"}}}},"output_flags":{"type":"array","items":{"type":"string"}}}}}},"tags":[{"name":"auth","description":"Sign in, OIDC, invites"},{"name":"workspaces","description":"Workspace + API key management"},{"name":"personas","description":"Persona CRUD + freeze"},{"name":"templates","description":"Built-in persona archetypes"},{"name":"chat","description":"Chat (streaming + non-streaming) + conversation history"},{"name":"memory","description":"Three-tier memory + recall + summarize"},{"name":"knowledge","description":"RAG: documents + chunks + search"},{"name":"pol","description":"Patterns of Life"},{"name":"autonomy","description":"Goal queue + tick + timeline"},{"name":"audit","description":"Hash-chained audit log + verify"},{"name":"billing","description":"Usage aggregation"},{"name":"events","description":"Server-Sent Events stream"},{"name":"replay","description":"Re-run any past turn"},{"name":"channels","description":"Inbound webhook + Slack"},{"name":"webhooks","description":"Outbound subscriptions"},{"name":"exports","description":"Workspace export + GDPR delete"}],"paths":{"/v1/personas":{"get":{"tags":["personas"],"summary":"List personas in the current workspace","responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Persona"}}}}}}}}},"post":{"tags":["personas"],"summary":"Create a persona","parameters":[{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}},"responses":{"201":{"description":"created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Persona"}}}}}}},"/v1/personas/{persona_id}":{"get":{"tags":["personas"],"parameters":[{"$ref":"#/components/parameters/personaId"}],"responses":{"200":{"description":"ok"},"404":{"description":"not_found"}}},"put":{"tags":["personas"],"parameters":[{"$ref":"#/components/parameters/personaId"}],"requestBody":{"required":true},"responses":{"200":{"description":"ok (version bumped)"}}},"delete":{"tags":["personas"],"parameters":[{"$ref":"#/components/parameters/personaId"}],"responses":{"200":{"description":"deleted"}}}},"/v1/personas/{persona_id}/freeze":{"post":{"tags":["personas"],"summary":"Emergency freeze — chat + autonomy refused (423) until thawed","parameters":[{"$ref":"#/components/parameters/personaId"}],"responses":{"200":{"description":"frozen"}}}},"/v1/personas/{persona_id}/thaw":{"post":{"tags":["personas"],"summary":"Unfreeze a previously frozen persona","parameters":[{"$ref":"#/components/parameters/personaId"}],"responses":{"200":{"description":"thawed"}}}},"/v1/chat":{"post":{"tags":["chat"],"summary":"Send a message; optionally stream the reply","parameters":[{"$ref":"#/components/parameters/idempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["persona_id","message"],"properties":{"persona_id":{"type":"string"},"message":{"type":"string"},"conversation_id":{"type":"string"},"stream":{"type":"boolean"}}}}}},"responses":{"200":{"description":"ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatReply"}}}},"429":{"description":"budget_exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/chat/conversations":{"get":{"tags":["chat"],"summary":"List conversations (optionally for one persona)","responses":{"200":{"description":"ok"}}}},"/v1/audit/verify":{"get":{"tags":["audit"],"summary":"Recompute the hash chain; { ok: boolean, broken_at?: id }","responses":{"200":{"description":"ok"}}}},"/v1/events/stream":{"get":{"tags":["events"],"summary":"Server-Sent Events stream of workspace events","responses":{"200":{"description":"text/event-stream"}}}},"/v1/exports/workspace":{"get":{"tags":["exports"],"summary":"Export the full workspace as a JSON document (personas, memory, conversations, audit, PoLs, autonomy, knowledge)","responses":{"200":{"description":"ok"}}}},"/v1/exports/workspace/delete":{"post":{"tags":["exports"],"summary":"GDPR delete — schedule the workspace for permanent deletion in 30 days","responses":{"200":{"description":"scheduled"}}}},"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"List outbound webhook subscriptions","responses":{"200":{"description":"ok"}}},"post":{"tags":["webhooks"],"summary":"Create an outbound subscription","parameters":[{"$ref":"#/components/parameters/idempotencyKey"}],"responses":{"201":{"description":"created"}}}},"/v1/webhooks/{id}":{"delete":{"tags":["webhooks"],"summary":"Revoke a subscription","responses":{"200":{"description":"revoked"}}}}}}