{"openapi":"3.1.0","info":{"title":"Quidwise CFO API","version":"1.0.0","summary":"One UK business's own finances, computed by the Quidwise engine, and questions to Ada, its AI finance director.","description":"Every request is scoped to the business the API key belongs to. The owner creates a key in Quidwise: Settings, API access; it is shown once.\n\nFor AI agents, the same business is also an MCP server at https://cfo.cijlabs.com/api/mcp (Streamable HTTP, the same key as a bearer token): ask_ada and Ada's read-only tools. See https://cfo.cijlabs.com/for-agents.\n\nFigures are computed by code from the business's bank feeds, accounting system and finance email; forecasts are 'if nothing changes' projections. Ada provides financial intelligence, not regulated financial, tax or legal advice.","contact":{"name":"CIJ Labs","email":"info@cijlabs.com","url":"https://cfo.cijlabs.com"}},"servers":[{"url":"https://cfo.cijlabs.com/api/v1","description":"This Quidwise server"}],"security":[{"apiKey":[]}],"externalDocs":{"description":"Quidwise for AI agents","url":"https://cfo.cijlabs.com/for-agents"},"tags":[{"name":"Business","description":"Who the key belongs to and what is connected"},{"name":"Figures","description":"The engine's output: snapshot, KPIs, the ledger and the bank feed"},{"name":"Reports","description":"The weekly edition and the Daily"},{"name":"Ada","description":"Questions to the AI finance director"}],"paths":{"/me":{"get":{"tags":["Business"],"operationId":"getMe","summary":"The business, its plan and its connections","responses":{"200":{"description":"The business","content":{"application/json":{"schema":{"type":"object","properties":{"org":{"type":"object","additionalProperties":true,"description":"id, name, plan, reportEmail"},"connections":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"kind, provider, status, lastSyncAt, tenantName"}},"authVia":{"type":"string","enum":["session","api_key"]}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/snapshot":{"get":{"tags":["Figures"],"operationId":"getSnapshot","summary":"The engine's output for the business (no raw ledger)","description":"Cash, runway, P&L, receivables and payables, the 13-week forecast, concentration, anomalies and the alerts. Refreshed from the sources when older than maxAgeHours.","parameters":[{"name":"maxAgeHours","in":"query","schema":{"type":"integer","minimum":1,"maximum":720,"default":24},"description":"Refresh first when the latest snapshot is older than this"}],"responses":{"200":{"description":"The snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"snapshotId":{"type":"string"},"snapshot":{"type":"object","additionalProperties":true,"description":"The Snapshot (src/engine/types.ts)"},"alerts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"An alert: level, title, detail"}},"bankFeed":{"type":"object","additionalProperties":true,"description":"Bank feed status, or null"}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing yet: connect a bank or an accounting system, or push a ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/kpis":{"get":{"tags":["Figures"],"operationId":"getKpis","summary":"The KPI board","responses":{"200":{"description":"The KPIs","content":{"application/json":{"schema":{"type":"object","properties":{"kpis":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"key, label, value, unit, target, rag, series"}}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Figures"],"operationId":"pushKpi","summary":"Push a value for one of your own KPIs (or the engine's)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["key","value"],"additionalProperties":false,"properties":{"key":{"type":"string","pattern":"^[a-z0-9_]{1,40}$"},"value":{"type":"number"},"label":{"type":"string","maxLength":80},"unit":{"type":"string","enum":["gbp","pct","count","days","months"]},"direction":{"type":"string","enum":["up","down"]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"target":{"type":["number","null"]}}}}}},"responses":{"200":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ok"}}}},"400":{"description":"The request is not valid; `error` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only: an operator is viewing this business as its owner sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ledger":{"get":{"tags":["Figures"],"operationId":"getLedger","summary":"The latest canonical ledger","responses":{"200":{"description":"The ledger","content":{"application/json":{"schema":{"type":"object","properties":{"snapshotId":{"type":"string"},"ledger":{"$ref":"#/components/schemas/Ledger"}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing yet: connect a bank or an accounting system, or push a ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Figures"],"operationId":"pushLedger","summary":"Push a ledger (makes it the business's accounting source and recomputes)","description":"How the CLI pushes CSV exports from any accounting package or a spreadsheet.","parameters":[{"name":"x-cij-source","in":"header","schema":{"type":"string"},"description":"A label for where the ledger came from (default api)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ledger"}}}},"responses":{"200":{"description":"Pushed and recomputed","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"snapshotId":{"type":"string"},"asOf":{"type":"string"},"cash":{"type":"number"},"alerts":{"type":"integer"}}}}}},"400":{"description":"The request is not valid; `error` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only: an operator is viewing this business as its owner sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bankfeed":{"get":{"tags":["Figures"],"operationId":"getBankFeed","summary":"The raw Open Banking feed, with how each line is categorised","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":540,"default":90}}],"responses":{"200":{"description":"The feed","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"historyFrom":{"type":["string","null"]},"warnings":{"type":"array","items":{"type":"string"}},"accounts":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"A bank account"}},"transactions":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"A transaction with counterparty, bucket and decidedBy"}}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing yet: connect a bank or an accounting system, or push a ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports":{"get":{"tags":["Reports"],"operationId":"listReports","summary":"Reports, newest first (summaries only)","parameters":[{"name":"cadence","in":"query","schema":{"type":"string","enum":["weekly","daily","all"],"default":"weekly"}}],"responses":{"200":{"description":"The reports","content":{"application/json":{"schema":{"type":"object","properties":{"reports":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"id, cadence, weekOf, summary, emailedAt, createdAt"}}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/{id}":{"get":{"tags":["Reports"],"operationId":"getReport","summary":"One report with its markdown narrative","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The report","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"type":"object","additionalProperties":true,"description":"The report row: narrativeMd, summary, weekOf, cadence"}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing yet: connect a bank or an accounting system, or push a ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reports/generate":{"post":{"tags":["Reports"],"operationId":"generateReport","summary":"Write this week's edition now","parameters":[{"name":"email","in":"query","schema":{"type":"string","enum":["1"]},"description":"1: also email it to the business's report address"}],"responses":{"200":{"description":"Written","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"reportId":{"type":"string"},"created":{"type":"boolean"},"emailed":{"type":"boolean"}}}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Read-only: an operator is viewing this business as its owner sees it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing yet: connect a bank or an accounting system, or push a ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ask":{"post":{"tags":["Ada"],"operationId":"askAda","summary":"Ask Ada a question (non-streaming)","description":"Ada answers from the business's own books with her tools; the tools she used come back in trace. The exchange is kept in the API key's own thread of her memory. 60 questions an hour per business.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["question"],"additionalProperties":false,"properties":{"question":{"type":"string","minLength":1,"maxLength":2000}}},"example":{"question":"When is my cash lowest in the next 13 weeks, and why?"}}}},"responses":{"200":{"description":"Ada's answer","content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string"},"trace":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"input":{},"summary":{"type":"string"}}}},"model":{"type":"string"},"usage":{"type":"object","properties":{"inputTokens":{"type":"integer"},"outputTokens":{"type":"integer"}}}}}}}},"400":{"description":"The request is not valid; `error` says why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or the key is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Nothing yet: connect a bank or an accounting system, or push a ledger.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; `error` says when to try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Ada's model could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"cij_live_…","description":"A Quidwise API key: Authorization: Bearer cij_live_…. The owner creates one in Settings, API access."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Ok":{"type":"object","properties":{"ok":{"type":"boolean","const":true}}},"Ledger":{"type":"object","properties":{"asOf":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"currency":{"default":"GBP","type":"string"},"orgName":{"type":"string","minLength":1},"accounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"class":{"type":"string","enum":["REVENUE","OTHERINCOME","DIRECTCOSTS","OVERHEADS","EXPENSE","BANK","CURRENT_ASSET","FIXED_ASSET","CURRENT_LIABILITY","LONGTERM_LIABILITY","EQUITY","OTHER"]}},"required":["id","name","class"]}},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"isCustomer":{"default":false,"type":"boolean"},"isSupplier":{"default":false,"type":"boolean"}},"required":["id","name"]}},"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","enum":["ACCREC","ACCPAY"]},"contactId":{"type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"dueDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"status":{"type":"string","enum":["DRAFT","AUTHORISED","PAID","VOIDED"]},"total":{"type":"number"},"amountPaid":{"type":"number"},"amountDue":{"type":"number"},"fullyPaidOn":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"lineItems":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"description":{"default":"","type":"string"},"amount":{"type":"number"}},"required":["accountId","amount"]}}},"required":["id","type","contactId","date","dueDate","status","total","amountPaid","amountDue","lineItems"]}},"bankTransactions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"bankAccountId":{"type":"string"},"type":{"type":"string","enum":["SPEND","RECEIVE"]},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"contactId":{"type":"string"},"reference":{"type":"string"},"total":{"type":"number"},"lineItems":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"description":{"default":"","type":"string"},"amount":{"type":"number"}},"required":["accountId","amount"]}}},"required":["id","bankAccountId","type","date","total","lineItems"]}},"bankAccounts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"default":"GBP","type":"string"},"balance":{"type":"number"}},"required":["id","name","balance"]}},"journals":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"narration":{"default":"","type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string"},"description":{"default":"","type":"string"},"amount":{"type":"number"}},"required":["accountId","amount"]}}},"required":["id","date","lines"]}}},"required":["asOf","orgName","accounts","contacts","invoices","bankTransactions","bankAccounts"],"description":"A ledger in Quidwise's canonical shape (src/engine/types.ts). Amounts in pounds, dates YYYY-MM-DD."}}}}