{"openapi":"3.1.0","info":{"title":"Brand Brain API","version":"1.0.0","description":"A brand's persistent memory and playbooks for AI assistants. Read the brand brief, propose changes, save drafts, record decisions and lessons, and resume where work stopped. Authenticate with a personal API key (prefix bbk_) as a bearer token or x-api-key header, or with an OAuth 2.1 token.","contact":{"url":"https://brain.fowl-ai.com/developers"}},"servers":[{"url":"https://brain.fowl-ai.com/api/v1"}],"security":[{"bearerAuth":[]},{"apiKey":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (bbk_…) or OAuth access token"},"apiKey":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Brand":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"updated_at":{"type":"string"},"sections_filled":{"type":"integer"},"sections_total":{"type":"integer"},"pending_proposals":{"type":"integer"},"outputs":{"type":"integer"}}},"Patch":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":true,"description":"Field key to new value (keys from GET /sections/{name})"},"markdown":{"type":"string","description":"Replace the whole worksheet"}}},"Proposal":{"type":"object","properties":{"id":{"type":"string"},"section":{"type":"string"},"status":{"type":"string","enum":["pending","applied","rejected"]},"summary":{"type":"string"},"diff_preview":{"type":"string"}}},"Output":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["website","landing_page","newsletter","social_post","email_sequence","pdf","avatar","launch_asset","campaign","video","trend_digest","proof","review","script","other"]},"slug":{"type":"string"},"title":{"type":"string"},"format":{"type":"string","enum":["markdown","html","text"]},"status":{"type":"string","enum":["draft","reviewed","remote_draft","scheduled","sent","published","unverified"]},"version":{"type":"integer"},"path":{"type":"string"}}},"SessionState":{"type":"object","properties":{"current_task":{"type":"string"},"latest_output_path":{"type":"string"},"observed_status":{"type":"string","enum":["local_draft","reviewed","remote_draft","scheduled","sent","unverified"]},"evidence":{"type":"string"},"confirmed_decisions":{"type":"string"},"unresolved_dependency":{"type":"string"},"next_step":{"type":"string"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}},"paths":{"/me":{"get":{"operationId":"getProfile","summary":"Who is connected","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands":{"get":{"operationId":"listBrands","summary":"List brands on the account. Call first to get a brand id.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"brands":{"type":"array","items":{"$ref":"#/components/schemas/Brand"}}}}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"post":{"operationId":"createBrand","summary":"Create a brand seeded with the 14 worksheets","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}":{"get":{"operationId":"getBrand","summary":"Whole brain: brief, sections, rules, session, decisions, proposals, outputs","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"include_markdown","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"delete":{"operationId":"deleteBrand","summary":"Delete a brand and everything in it","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/sections/{name}":{"get":{"operationId":"getSection","summary":"One section: fields, valid keys, raw markdown","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"name","in":"path","required":true,"schema":{"type":"string","enum":["mission","audience","positioning","visual-direction","brand-voice","messaging","offer","products","social-proof","content-system","newsletter","website","faq","launch-plan"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"put":{"operationId":"updateSection","summary":"Update a section. Applies immediately unless propose=true.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"name","in":"path","required":true,"schema":{"type":"string","enum":["mission","audience","positioning","visual-direction","brand-voice","messaging","offer","products","social-proof","content-system","newsletter","website","faq","launch-plan"]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fields":{"type":"object","additionalProperties":true},"markdown":{"type":"string"},"summary":{"type":"string","description":"One line on what changed"},"rationale":{"type":"string"},"source":{"type":"string"},"propose":{"type":"boolean","description":"Leave as a pending proposal for the person to review"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"proposal":{"$ref":"#/components/schemas/Proposal"}}}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/proposals":{"get":{"operationId":"listProposals","summary":"Proposals on a brand","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","applied","rejected"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"post":{"operationId":"proposeUpdate","summary":"Propose a change to a section (pending unless confirmed)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"section":{"type":"string","enum":["mission","audience","positioning","visual-direction","brand-voice","messaging","offer","products","social-proof","content-system","newsletter","website","faq","launch-plan"]},"patch":{"$ref":"#/components/schemas/Patch"},"summary":{"type":"string"},"rationale":{"type":"string"},"source":{"type":"string"},"confirmed":{"type":"boolean"}},"required":["section","patch","summary"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/proposals/{pid}":{"post":{"operationId":"resolveProposal","summary":"Apply or reject a proposal","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"pid","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["apply","reject"]},"note":{"type":"string"}},"required":["decision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/outputs":{"get":{"operationId":"listOutputs","summary":"Saved drafts","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"type","in":"query","schema":{"type":"string","enum":["website","landing_page","newsletter","social_post","email_sequence","pdf","avatar","launch_asset","campaign","video","trend_digest","proof","review","script","other"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","reviewed","remote_draft","scheduled","sent","published","unverified"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"post":{"operationId":"saveOutput","summary":"Save or update a draft (upsert by type+slug). Never publishes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["website","landing_page","newsletter","social_post","email_sequence","pdf","avatar","launch_asset","campaign","video","trend_digest","proof","review","script","other"]},"slug":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"format":{"type":"string","enum":["markdown","html","text"]},"status":{"type":"string","enum":["draft","reviewed","remote_draft","scheduled","sent","published","unverified"]},"note":{"type":"string"}},"required":["type","slug","title","content"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"output":{"$ref":"#/components/schemas/Output"}}}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/outputs/{type}/{slug}":{"get":{"operationId":"getOutput","summary":"One draft in full (paged with offset/max_chars)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["website","landing_page","newsletter","social_post","email_sequence","pdf","avatar","launch_asset","campaign","video","trend_digest","proof","review","script","other"]}},{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"offset","in":"query","schema":{"type":"integer"}},{"name":"max_chars","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/decisions":{"get":{"operationId":"listDecisions","summary":"Decision log","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"post":{"operationId":"logDecision","summary":"Record a direction-setting decision","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string"},"reason":{"type":"string"}},"required":["decision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/rules":{"get":{"operationId":"listRules","summary":"House rules","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"post":{"operationId":"addRule","summary":"Add a house rule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"string"},"why":{"type":"string"},"how_to_apply":{"type":"string"},"source":{"type":"string"}},"required":["rule"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/rules/{rid}":{"delete":{"operationId":"deleteRule","summary":"Remove a house rule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"rid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/lessons":{"get":{"operationId":"listLessons","summary":"Lessons captured for this brand","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"post":{"operationId":"logLesson","summary":"Capture a lesson; promote_to_rule adds it as a house rule","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trigger":{"type":"string"},"evidence":{"type":"string"},"decision":{"type":"string"},"correction":{"type":"string","enum":["proposed","implemented","verified"]},"portability":{"type":"string"},"reuse_destination":{"type":"string"},"promote_to_rule":{"type":"boolean"}},"required":["trigger","decision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/session":{"get":{"operationId":"getSession","summary":"Where work stopped","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"session_state":{"$ref":"#/components/schemas/SessionState"}}}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}},"patch":{"operationId":"setSession","summary":"Save where work stopped (partial merge)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionState"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/search":{"get":{"operationId":"searchBrand","summary":"Text search across sections, outputs, decisions, rules","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"q","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/import":{"post":{"operationId":"importWorkspace","summary":"Import a Brand Brain workspace (zip or {files}); mode=propose|replace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"mode","in":"query","schema":{"type":"string","enum":["propose","replace"]}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"object","additionalProperties":{"type":"string"}}},"required":["files"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}},"application/zip":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/brands/{id}/export":{"get":{"operationId":"exportWorkspace","summary":"Export the brand as workspace files (json or zip)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Brand id, from GET /brands."},{"name":"format","in":"query","schema":{"type":"string","enum":["json","zip"]}}],"responses":{"200":{"description":"Files","content":{"application/json":{"schema":{"type":"object","properties":{"files":{"type":"object","additionalProperties":{"type":"string"}}}}},"application/zip":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}},"/prompts":{"get":{"operationId":"listPlaybooks","summary":"Playbook catalogue (no auth)","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/prompts/{name}":{"get":{"operationId":"getPlaybook","summary":"One playbook rendered with a brand's brief","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"brand_id","in":"query","schema":{"type":"string"}},{"name":"task","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"Missing or invalid credential"},"402":{"description":"No active plan for writes"},"403":{"description":"Insufficient scope"},"404":{"description":"Not found"}}}}},"externalDocs":{"url":"https://brain.fowl-ai.com/developers","description":"How to connect. MCP endpoint: https://brain.fowl-ai.com/mcp"}}