{ "openapi": "3.1.0", "info": { "title": "Candor API", "version": "2026-08-12", "summary": "Give an authorized AI agent access to personal finance records for accounts, spending, budgets, goals, and investments." }, "servers": [ { "url": "https://api.candor.money" } ], "security": [ { "candorBearer": [] } ], "paths": { "/v1/open": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return new activity since this credential's acknowledged checkpoint plus current attention.", "responses": { "200": { "description": "Workspace opening envelope." } } } }, "/v1/open/pulse": { "parameters": [ { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Quietly check whether the financial workspace needs inspection.", "responses": { "200": { "description": "Bounded workspace pulse envelope." } } } }, "/v1/open/acknowledge": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Monotonically acknowledge a workspace-opening checkpoint for this credential.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceOpenAcknowledgeRequest" } } } }, "responses": { "200": { "description": "Workspace checkpoint acknowledgement envelope." } } } }, "/v1/schema": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Describe the current financial workspace contract.", "responses": { "200": { "description": "Workspace schema envelope." } } } }, "/v1/actions": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List Candor actions and why they happened, or return one action with its outcomes and scopes.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "in": "query", "name": "task_key", "schema": { "type": "string" }, "description": "Return only actions labelled with this task key." }, { "in": "query", "name": "include_pulse", "schema": { "type": "boolean", "default": false }, "description": "Include routine workspace pulse actions that are hidden from the default orientation view." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Action history envelope." } } } }, "/v1/data": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List the financial datasets available in Candor.", "responses": { "200": { "description": "Dataset registry envelope." } } } }, "/v1/data/schema": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Describe one financial dataset and its fields.", "parameters": [ { "in": "query", "name": "dataset", "required": true, "schema": { "type": "string" }, "description": "The dataset to describe. `candor data list` names them." } ], "responses": { "200": { "description": "Dataset schema envelope." } } } }, "/v1/data/query": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Run one bounded query against a declared financial dataset.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetQueryRequest" } } } }, "responses": { "200": { "description": "Bounded dataset result envelope." } } } }, "/v1/goals": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List goals or return one goal by id.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "archived" ] }, "description": "Return only records in this state." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Goal state envelope." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create an approved goal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalCreateRequest" } } } }, "responses": { "200": { "description": "Created goal envelope." } } } }, "/v1/goals/history": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return approved versions for one goal.", "parameters": [ { "in": "query", "name": "goal_id", "required": true, "schema": { "type": "string" }, "description": "The goal this concerns." } ], "responses": { "200": { "description": "Goal history envelope." } } } }, "/v1/goals/update": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create a new approved goal version.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalUpdateRequest" } } } }, "responses": { "200": { "description": "Updated goal envelope." } } } }, "/v1/goals/archive": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Archive a goal.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalArchiveRequest" } } } }, "responses": { "200": { "description": "Archived goal envelope." } } } }, "/v1/goals/progress": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Record a goal progress event.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GoalProgressRequest" } } } }, "responses": { "200": { "description": "Goal progress envelope." } } } }, "/v1/impacts": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List financial impacts or return one impact by id.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one impact with one page of its append-only history instead of a list." }, { "in": "query", "name": "state", "schema": { "type": "string", "enum": [ "identified", "acted", "outcome_observed", "realized", "closed_without_value", "reverted" ] }, "description": "Return only impacts at this lifecycle state. This is separate from how strongly a value is evidenced." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum impacts to list, or maximum history events when id is present. Ask for what you will read." }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Continue the same filtered list from next_cursor, or the same impact history from events_next_cursor when id is present." } ], "responses": { "200": { "description": "Financial impact envelope." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Record an identified financial impact.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialImpactCreateRequest" } } } }, "responses": { "200": { "description": "Created financial impact envelope." } } } }, "/v1/impacts/record": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Append an action, value, correction, closure, or reversal to one financial impact.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialImpactRecordRequest" } } } }, "responses": { "200": { "description": "Updated financial impact envelope." } } } }, "/v1/impacts/summary": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Summarize potential and realized impact in separate typed buckets.", "responses": { "200": { "description": "Financial impact summary envelope." } } } }, "/v1/notes": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List bounded agent-authored notes or return one note by id.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "all", "resolved" ] }, "description": "Return only records in this state." }, { "in": "query", "name": "due", "schema": { "type": "boolean" }, "description": "Return only notes whose revisit time has arrived. This is the set an opening surfaces." }, { "in": "query", "name": "before", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive upper bound on the revisit time. A note exactly on the boundary is returned, so adjacent windows built from these bounds overlap by one instant." }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "date-time" }, "description": "Inclusive lower bound on the revisit time. A note exactly on the boundary is returned, so adjacent windows built from these bounds overlap by one instant." }, { "in": "query", "name": "updated_after", "schema": { "type": "string", "format": "date-time" }, "description": "Return only records changed after this time, for catching up rather than re-reading everything. Pair it with status all; the default active status rejects it as unsupported_note_update_filters." }, { "in": "query", "name": "about", "schema": { "type": "string" }, "description": "Return only notes linked to this record, written as RESOURCE:ID, such as transactions:TRANSACTION_ID. A bare id is rejected as invalid_note_about." }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Full-text search over note bodies, matching whole tokens rather than substrings: `script` will not find `subscription`. A miss is not evidence that no note exists." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." } ], "responses": { "200": { "description": "Note envelope." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create a stable Markdown note with optional resource and revisit time.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteCreateRequest" } } } }, "responses": { "200": { "description": "Created note envelope." } } } }, "/v1/notes/update": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Update a note in place without changing its id.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteUpdateRequest" } } } }, "responses": { "200": { "description": "Updated note envelope." } } } }, "/v1/notes/resolve": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Resolve a note.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteIdRequest" } } } }, "responses": { "200": { "description": "Resolved note envelope." } } } }, "/v1/notes/reopen": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Reopen a resolved note.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteIdRequest" } } } }, "responses": { "200": { "description": "Reopened note envelope." } } } }, "/v1/status": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "security": [], "summary": "Return Candor account, financial connection, and client compatibility status.", "responses": { "200": { "description": "Versioned response envelope." } } } }, "/v1/plaid/link-token": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create a Plaid Link token for a new connection.", "responses": { "200": { "description": "Envelope with linkToken, expiration, and requestId." } } } }, "/v1/plaid/exchange": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Exchange a Plaid public token and run initial sync.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "public_token" ], "properties": { "public_token": { "type": "string", "description": "The short-lived token the connection handoff returned. It is single-use." }, "institution_name": { "type": "string" }, "institution_id": { "type": "string" }, "link_session_id": { "type": "string" } } } } } }, "responses": { "200": { "description": "Envelope with connection and sync counts." } } } }, "/v1/link/reconnect": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create a Plaid Link update-mode token for reconnecting an existing connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_connection_id" ], "properties": { "source_connection_id": { "type": "string", "description": "The source connection this concerns." } } } } } }, "responses": { "200": { "description": "Envelope with update-mode link token and connectionId." } } } }, "/v1/link/disconnect": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Remove the Plaid Item and clear local token custody.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_connection_id" ], "properties": { "source_connection_id": { "type": "string", "description": "The source connection this concerns." } } } } } }, "responses": { "200": { "description": "Envelope with disconnect cleanup status." } } } }, "/v1/link/connections": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List connections or return one connection by id query parameter.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with provider connection facts." } } } }, "/v1/sync/refresh": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Refresh all active connections or one connection.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "source_connection_id": { "type": "string", "description": "The source connection this concerns." }, "connection_id": { "type": "string", "description": "Accepted alias for source_connection_id." }, "force": { "type": "boolean", "description": "Force a refresh even when sync metadata is fresh." } } } } } }, "responses": { "200": { "description": "Envelope with sync counts and policy skip summaries." } } } }, "/v1/sync/runs": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List sync runs or return one sync run by id query parameter.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with sync run facts." } } } }, "/v1/accounts": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List accounts or return one account by id query parameter.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Response containing Candor accounts." } } } }, "/v1/accounts/policy": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return the active inclusion and role policy for an account identity.", "parameters": [ { "in": "query", "name": "account_identity_id", "required": true, "schema": { "type": "string" }, "description": "Restrict to one durable account identity across source connections." } ], "responses": { "200": { "description": "Envelope with the active account policy or null." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Store an approved account inclusion and role policy.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPolicyRequest" } } } }, "responses": { "200": { "description": "Envelope with the active approved account policy." } } } }, "/v1/accounts/policy/revert": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Revert an account identity to default inclusion and derived role.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_identity_id" ], "properties": { "account_identity_id": { "type": "string", "description": "The durable account identity this concerns, which survives a reconnected source connection." } } } } } }, "responses": { "200": { "description": "Envelope with the reverted account policy id." } } } }, "/v1/account-terms/assertion": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return the active approved assertion for one canonical account term.", "parameters": [ { "in": "query", "name": "account_identity_id", "required": true, "schema": { "type": "string" }, "description": "The durable account identity whose term was asserted." }, { "in": "query", "name": "field", "required": true, "schema": { "type": "string" }, "description": "The canonical account-term field, such as apr.purchase or apy." } ], "responses": { "200": { "description": "Envelope with the active assertion or null." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Store an approved assertion for one canonical account term.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountTermAssertionRequest" } } } }, "responses": { "200": { "description": "Envelope with the stored assertion and any superseded assertion id." } } } }, "/v1/account-terms/assertion/history": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return versioned assertion history for one canonical account term.", "parameters": [ { "in": "query", "name": "account_identity_id", "required": true, "schema": { "type": "string" }, "description": "The durable account identity whose assertion history is requested." }, { "in": "query", "name": "field", "required": true, "schema": { "type": "string" }, "description": "The canonical account-term field." }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Maximum assertion versions to return, newest first." }, { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Continue from the next_cursor returned by a prior bounded assertion-history page." } ], "responses": { "200": { "description": "Envelope with bounded assertion history." } } } }, "/v1/account-terms/assertion/preview": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Preview an approved account-term assertion without writing it.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountTermAssertionRequest" } } } }, "responses": { "200": { "description": "Envelope with the proposed assertion and the version it would supersede." } } } }, "/v1/account-terms/assertion/revert": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Revert the active approved assertion for one canonical account term.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "account_identity_id", "field" ], "properties": { "account_identity_id": { "type": "string", "description": "The durable account identity whose assertion is being reverted." }, "field": { "type": "string", "description": "The canonical account-term field." } } } } } }, "responses": { "200": { "description": "Envelope with the reverted assertion id." } } } }, "/v1/balances": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return current cached account balances.", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with balance facts." } } } }, "/v1/coverage": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return provider product coverage and freshness facts.", "responses": { "200": { "description": "Envelope with coverage status." } } } }, "/v1/debts/summary": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return visible debt posture facts.", "responses": { "200": { "description": "Envelope with debt summary." } } } }, "/v1/liquidity": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return visible liquidity and net position facts.", "responses": { "200": { "description": "Envelope with liquidity summary." } } } }, "/v1/net-worth": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return visible net worth facts from observed balances and supported manual holding market estimates.", "responses": { "200": { "description": "Envelope with visible asset, liability, and net worth facts plus coverage caveats." } } } }, "/v1/metrics/history": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return auditable metric time series from stored observations and transaction reconstruction.", "parameters": [ { "in": "query", "name": "metric", "schema": { "type": "string", "default": "visible_net_position" }, "description": "Which metric to return." }, { "in": "query", "name": "range", "schema": { "type": "string", "enum": [ "week", "month", "3m", "ytd", "year" ], "default": "month" }, "description": "How far back to read." }, { "in": "query", "name": "granularity", "schema": { "type": "string", "enum": [ "day", "week", "month" ] }, "description": "Bucket size for the series." }, { "in": "query", "name": "currency", "schema": { "type": "string" }, "description": "Restrict to this ISO currency code." } ], "responses": { "200": { "description": "Envelope with metric buckets, provenance, freshness, coverage, caveats, and basis handles." } } } }, "/v1/metrics/refresh": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Request an explicit provider-backed metric refresh when freshness warrants the cost.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "metric": { "type": "string", "default": "visible_net_position" }, "range": { "type": "string", "enum": [ "week", "month", "3m", "ytd", "year" ], "default": "month" }, "policy": { "type": "string", "enum": [ "if_stale", "if_missing", "force", "never" ], "default": "if_stale" }, "max_provider_calls": { "type": "integer", "minimum": 0, "default": 0 }, "source_connection_id": { "type": "string", "description": "The source connection this concerns." }, "connection_id": { "type": "string" }, "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Envelope with provider call budget, skip reason, sync summary, and follow-up history command." } } } }, "/v1/changes": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return computed changes between current and comparison records.", "parameters": [ { "in": "query", "name": "domain", "schema": { "type": "string", "enum": [ "all", "spending", "income", "recurring", "account_terms" ] }, "description": "Restrict to this change domain." }, { "in": "query", "name": "account_identity_id", "schema": { "type": "string" }, "description": "Restrict transaction and account-term changes to one durable account identity before applying history caps. This scope applies to spending, income, recurring, account_terms, and all domains." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." } ], "responses": { "200": { "description": "Envelope with change items, caveats, basis handles, and drilldown commands." } } } }, "/v1/spending/categories": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return spending category facts with cashflow roles separated.", "parameters": [ { "in": "query", "name": "since", "schema": { "type": "string" }, "description": "Earliest date to include, as an ISO calendar date. Omitting it reads the default window, which may not cover the period you are reasoning about." }, { "in": "query", "name": "until", "schema": { "type": "string" }, "description": "Latest date to include, as an ISO calendar date." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." } ], "responses": { "200": { "description": "Envelope with expense category totals, cashflow role totals, caveats, and basis handles." } } } }, "/v1/merchants": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return merchant aggregates from posted transactions.", "parameters": [ { "in": "query", "name": "merchant", "schema": { "type": "string" }, "description": "Match this merchant. Names drift between statements, so treat one spelling as a hypothesis rather than the whole history." }, { "in": "query", "name": "since", "schema": { "type": "string" }, "description": "Earliest date to include, as an ISO calendar date. Omitting it reads the default window, which may not cover the period you are reasoning about." }, { "in": "query", "name": "until", "schema": { "type": "string" }, "description": "Latest date to include, as an ISO calendar date." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." } ], "responses": { "200": { "description": "Envelope with merchant aggregates, role totals, caveats, and transaction drilldown commands." } } } }, "/v1/budget/context": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return budget setup context for an agent-authored budget proposal.", "parameters": [ { "in": "query", "name": "period", "schema": { "type": "string" }, "description": "The plan period to read, as YYYY-MM." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." } ], "responses": { "200": { "description": "Envelope with category baselines, recurring candidates, active budget, and suggested commands." } } } }, "/v1/budget/plan": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Store an approved agent-authored category budget plan.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "period", "currency", "lines" ], "anyOf": [ { "required": [ "approval_note" ] }, { "required": [ "approval_source" ] } ], "description": "An approved plan, not an observation. Storing one supersedes the active plan for that period, so read the current plan and the observed spending it is meant to reflect before writing. Either approval_note or approval_source is required, because a plan nobody agreed to is a guess with a deadline attached.", "properties": { "period": { "type": "string", "description": "The month this plan governs, as YYYY-MM." }, "currency": { "type": "string", "description": "Three-letter uppercase ISO code the plan is denominated in, such as USD. Every line amount is read in it, so a plan in the wrong currency compares against the wrong spending." }, "approval_note": { "type": "string", "description": "What the user actually approved, in their terms. What they intend to spend encodes their priorities, so this records their decision rather than an average of past months." }, "approval_source": { "type": "string", "description": "Where that approval happened, such as the conversation or message it came from." }, "policy_notes": { "type": "string" }, "recurs_monthly": { "type": "boolean", "description": "Whether this plan should carry into later months instead of applying to this period alone." }, "lines": { "type": "array", "description": "Replaces the whole plan as a set. A category left out is unbudgeted, not carried over from the previous plan.", "items": { "type": "object", "required": [ "category", "monthly_amount", "line_type" ], "properties": { "category": { "type": "string", "description": "The effective category this line governs, matching the category transactions carry after corrections and rules. A category nothing resolves to allocates money against spending that never arrives." }, "monthly_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "A positive plain decimal in the plan's currency, with no symbol or code: `250.00`, not `$250` or `USD 250.00`." }, "line_type": { "type": "string", "enum": [ "recurring", "flexible", "goal", "cushion", "other" ], "description": "How the line behaves against actuals: recurring is a committed obligation, flexible is discretionary, goal funds an approved goal, and cushion is deliberate slack rather than a spending target." }, "policy_note": { "type": "string" }, "rollover_enabled": { "type": "boolean", "description": "Whether an underspend carries into the next period instead of resetting. This depends on the plan recurring: with recurs_monthly false there is no next period to carry into, and the request returns a warning saying nothing will accumulate." } } } } } } } } }, "responses": { "200": { "description": "Envelope with the active budget plan, plan lines, and superseded plan ids." } } } }, "/v1/budget/status": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return active budget variance and safe-to-spend facts.", "parameters": [ { "in": "query", "name": "period", "schema": { "type": "string" }, "description": "The plan period to read, as YYYY-MM." }, { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." } ], "responses": { "200": { "description": "Envelope with active budget lines, actuals, variance, caveats, and suggested commands." } } } }, "/v1/imports/validate": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Validate an agent-curated financial import manifest.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CuratedImportManifest" } } } }, "responses": { "200": { "description": "Envelope with validation issues, normalized rows, and suggested commands." } } } }, "/v1/imports/preview": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Preview how a proposed import would affect Candor financial records.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CuratedImportManifest" } } } }, "responses": { "200": { "description": "Envelope with an import batch, row actions, issues, and suggested commands." } } } }, "/v1/imports/apply": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Apply a previewed curated import after explicit user approval.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "import_batch_id" ], "properties": { "import_batch_id": { "type": "string", "description": "The import batch this concerns, as returned by the preview." }, "approval_note": { "type": "string" }, "approved_by": { "type": "string" } } } } } }, "responses": { "200": { "description": "Envelope with created/skipped transaction counts and basis handles." } } } }, "/v1/imports": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return curated import batch status and row decisions.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with import batches or a single import batch and rows." } } } }, "/v1/imports/revert": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Revert Candor records created or changed by an approved import batch.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "import_batch_id" ], "properties": { "import_batch_id": { "type": "string", "description": "The import batch this concerns, as returned by the preview." } } } } } }, "responses": { "200": { "description": "Envelope with reverted transaction counts." } } } }, "/v1/manual/accounts/preview": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Preview a manual account entry through the curated import pipeline.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualAccountPreviewRequest" } } } }, "responses": { "200": { "description": "Envelope with the staged import batch and approval command." } } } }, "/v1/manual/transactions/preview": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Preview a manual transaction through the curated import pipeline.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualTransactionPreviewRequest" } } } }, "responses": { "200": { "description": "Envelope with the staged import batch and approval command." } } } }, "/v1/transactions": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List transactions or return one transaction by id query parameter.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "in": "query", "name": "since", "schema": { "type": "string" }, "description": "Earliest date to include, as an ISO calendar date. Omitting it reads the default window, which may not cover the period you are reasoning about." }, { "in": "query", "name": "until", "schema": { "type": "string" }, "description": "Latest date to include, as an ISO calendar date." }, { "in": "query", "name": "category", "schema": { "type": "string" }, "description": "Match this category, as it stands after corrections and rules." }, { "in": "query", "name": "merchant", "schema": { "type": "string" }, "description": "Match this merchant. Names drift between statements, so treat one spelling as a hypothesis rather than the whole history." }, { "in": "query", "name": "source_account_id", "schema": { "type": "string", "minLength": 1 }, "description": "Restrict transactions to one visible account using the exact id returned by accounts.list. Omit this filter to return transactions across every visible account." }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/PageLimit" } ], "responses": { "200": { "description": "Envelope with transactions and pagination." } } } }, "/v1/transactions/split": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return the active allocation overlay for a transaction.", "parameters": [ { "in": "query", "name": "transaction_id", "required": true, "schema": { "type": "string" }, "description": "The canonical transaction this concerns." } ], "responses": { "200": { "description": "Envelope with the active split or null." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Replace a transaction's approved category allocation overlay.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionSplitRequest" } } } }, "responses": { "200": { "description": "Envelope with the active split and allocation lines." } } } }, "/v1/transactions/split/revert": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Revert the active allocation overlay for a transaction.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "description": "The canonical transaction this concerns." } } } } } }, "responses": { "200": { "description": "Envelope with the reverted split id." } } } }, "/v1/corrections": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return exact-record typed-rule application history.", "parameters": [ { "in": "query", "name": "transaction_id", "schema": { "type": "string" }, "description": "The canonical transaction this concerns." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with transaction correction records." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create and apply an exact-record normalization rule.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "transaction_id" ], "anyOf": [ { "required": [ "effective_label" ] }, { "required": [ "effective_category" ] }, { "required": [ "effective_cashflow_role" ] }, { "required": [ "add_tags" ] }, { "required": [ "remove_tags" ] }, { "required": [ "review_status" ] } ], "properties": { "transaction_id": { "type": "string", "description": "The canonical transaction to correct. A correction applies to this record only; use a rule when the meaning should apply to future transactions too." }, "effective_label": { "type": "string", "description": "What this merchant should read as. The source label is kept, so a correction records the user's meaning rather than overwriting evidence." }, "effective_category": { "type": "string", "description": "The category this transaction should count under." }, "effective_cashflow_role": { "type": "string", "description": "Whether the money moved rather than being spent. A transfer or debt payment miscounted as expense distorts every spending total that follows." }, "add_tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to add to this transaction." }, "remove_tags": { "type": "array", "items": { "type": "string" }, "description": "Tags to remove from this transaction." }, "review_status": { "type": "string", "description": "Where this record stands in review." }, "reason": { "type": "string", "description": "Concise user-visible reason for the correction, recorded on the action." }, "set_by": { "type": "string", "description": "Who established the correction." } } } } } }, "responses": { "200": { "description": "Envelope with correction basis, object counts, and suggested commands." } } } }, "/v1/transactions/summary": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Return bounded transaction summary statistics.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "limit": { "type": "integer" }, "since": { "type": "string" }, "until": { "type": "string" } } } } } }, "responses": { "200": { "description": "Envelope with transaction summary." } } } }, "/v1/rules": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List typed interpretation rules.", "parameters": [ { "in": "query", "name": "family", "schema": { "type": "string", "enum": [ "normalization" ] }, "description": "Restrict to one rule family." }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "active", "disabled" ] }, "description": "Return only records in this state." }, { "in": "query", "name": "target", "schema": { "type": "string" }, "description": "Restrict to rules that change this part of a record." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with typed rules, selectors, effects, authority, and basis." } } }, "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Create a typed interpretation rule.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterpretationRuleCreateRequest" } } } }, "responses": { "200": { "description": "Envelope with rule metadata, caveats, and suggested commands." } } } }, "/v1/rules/preview": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Preview rule impact before applying materialized effects.", "responses": { "200": { "description": "Envelope with preview id, matched counts, basis, and approval requirements." } } } }, "/v1/rules/apply": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Apply a previously previewed typed rule.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "rule_id", "preview_id" ], "properties": { "rule_id": { "type": "string", "description": "The rule to apply, as returned when it was created." }, "preview_id": { "type": "string", "description": "The preview whose result you are accepting. Applying without one is rejected: the preview is what shows which transactions the rule reaches, and a rule is applied to what was inspected rather than to whatever it matches now." } } } } } }, "responses": { "200": { "description": "Envelope with applied correction counts and basis." } } } }, "/v1/rules/disable": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Disable a typed rule so it no longer affects future interpretation.", "responses": { "200": { "description": "Envelope with disabled rule metadata, basis, and object counts." } } } }, "/v1/rules/revert": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Revert an exact rule application or application batch.", "responses": { "200": { "description": "Envelope with reverted correction counts and basis." } } } }, "/v1/recurring": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List persisted recurring items.", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with recurring items." } } } }, "/v1/recurring/candidates": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return deterministic recurring candidates from transaction history.", "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer" }, "description": "Maximum records to return. Ask for what you will read; a large page costs context you may need for the answer." }, { "in": "query", "name": "direction", "description": "Narrow before the page is cut, so a role cannot be crowded out.", "schema": { "type": "string", "enum": [ "inflow", "outflow", "neutral" ] } }, { "in": "query", "name": "cashflow_role", "description": "Narrow before the page is cut, so a role cannot be crowded out.", "schema": { "type": "string", "enum": [ "income", "expense", "transfer", "debt_payment", "refund", "unknown" ] } } ], "responses": { "200": { "description": "Envelope with recurring candidates." } } } }, "/v1/recurring/policy": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Confirm, correct, stop, or dismiss a false recurring detection as approved workspace state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPolicyRequest" } } } }, "responses": { "200": { "description": "Envelope with the active recurring policy." } } } }, "/v1/recurring/policy/revert": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Revert a recurring item to inferred source-backed state.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "recurring_item_id" ], "properties": { "recurring_item_id": { "type": "string", "description": "The recurring item this concerns." } } } } } }, "responses": { "200": { "description": "Envelope with the reverted recurring policy id." } } } }, "/v1/holdings": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List synced investment holdings.", "parameters": [ { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" }, { "in": "query", "name": "source_account_id", "schema": { "type": "string", "minLength": 1 }, "description": "Restrict positions to one visible source account." } ], "responses": { "200": { "description": "Response containing Candor investment holdings." } } } }, "/v1/portfolio/snapshot": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Return portfolio snapshot facts from synced balances and holdings.", "responses": { "200": { "description": "Envelope with portfolio snapshot." } } } }, "/v1/audit": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "List audit events or return one event by id query parameter.", "parameters": [ { "in": "query", "name": "id", "schema": { "type": "string" }, "description": "Return this one record instead of a list. Use the exact id a prior call returned." }, { "$ref": "#/components/parameters/PageLimit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "Envelope with audit events." } } } }, "/v1/vault/delete": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "post": { "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "summary": "Erase the deletable online vault workspace and revoke local access after explicit confirmation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "confirm" ], "properties": { "confirm": { "const": "DELETE", "description": "Type the exact required value. This is irreversible, and the value exists so it cannot be sent by accident." } } } } } }, "responses": { "200": { "description": "Envelope with delete cleanup status." } } } }, "/v1/skill": { "get": { "security": [], "summary": "Return recommended hosted agent setup, install, and skill metadata.", "responses": { "200": { "description": "Versioned response envelope." } } } }, "/v1/skills": { "parameters": [ { "$ref": "#/components/parameters/ActionReason" }, { "$ref": "#/components/parameters/ParentAction" }, { "$ref": "#/components/parameters/ActionTaskKey" } ], "get": { "summary": "Inspect the available Candor finance package or load one method file.", "parameters": [ { "in": "query", "name": "bundle", "description": "Set to `1` to download the complete verified finance package in one signed-in response.", "schema": { "type": "string", "enum": [ "1" ] } }, { "in": "query", "name": "skill_id", "description": "Select `candor-finance`. Omit it to inspect the finance package available from Candor.", "schema": { "type": "string" } }, { "in": "query", "name": "resource_path", "description": "Select a method or reference file from the hosted package. Omit it to load the package's primary `SKILL.md`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Finance skill response after checking account access." } } } } }, "components": { "securitySchemes": { "candorBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Run `candor setup`; the CLI completes OAuth authorization-code with PKCE, stores only its refresh credential in the configured secure credential store, and sends a short-lived JWT access token." } }, "parameters": { "PageLimit": { "in": "query", "name": "limit", "required": false, "description": "Maximum records to return in one page. The supported range is 1 through 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, "Cursor": { "in": "query", "name": "cursor", "required": false, "description": "Continue the same filtered read from pagination.next_cursor.", "schema": { "type": "string", "minLength": 1 } }, "IdempotencyKey": { "in": "header", "name": "Idempotency-Key", "required": true, "description": "Stable opaque identity for one logical POST. Reuse only with the same method, path, actor, and body.", "schema": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[\\x20-\\x7E]+$" } }, "ActionReason": { "in": "header", "name": "X-Candor-Reason", "required": false, "description": "Concise user-visible reason for the root Candor operation. Required unless X-Candor-Parent-Action continues an existing action.", "schema": { "type": "string", "minLength": 1, "maxLength": 280 } }, "ActionTaskKey": { "in": "header", "name": "X-Candor-Task-Key", "required": false, "description": "Stable key for grouping operations that continue the same user task.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "ParentAction": { "in": "header", "name": "X-Candor-Parent-Action", "required": false, "description": "Existing action id whose reason and root identity this operation continues. Required unless X-Candor-Reason starts a root action.", "schema": { "type": "string", "minLength": 1 } } }, "schemas": { "MoneyInput": { "type": "string", "maxLength": 32, "oneOf": [ { "pattern": "^(?:CLP|JPY|KRW) -?(?:(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6])|9223372036854775807)$" }, { "pattern": "^(?:AUD|BRL|CAD|CHF|CNY|EUR|GBP|HKD|INR|MXN|NZD|SGD|USD) -?(?:(?:0|[1-9][0-9]{0,15}|[1-8][0-9]{16}|9[0-1][0-9]{15}|92[0-1][0-9]{14}|922[0-2][0-9]{13}|9223[0-2][0-9]{12}|92233[0-6][0-9]{11}|922337[0-1][0-9]{10}|92233720[0-2][0-9]{8}|922337203[0-5][0-9]{7}|9223372036[0-7][0-9]{6}|92233720368[0-4][0-9]{5}|922337203685[0-3][0-9]{4}|9223372036854[0-6][0-9]{3}|92233720368547[0-6][0-9]{2}|922337203685477[0-4][0-9]{1}|9223372036854775[0-7])(?:[.][0-9]{1,2})?|92233720368547758(?:[.](?:0|(?:0[0-6]|07)))?)$" }, { "pattern": "^(?:BHD|KWD|OMR) -?(?:(?:0|[1-9][0-9]{0,14}|[1-8][0-9]{15}|9[0-1][0-9]{14}|92[0-1][0-9]{13}|922[0-2][0-9]{12}|9223[0-2][0-9]{11}|92233[0-6][0-9]{10}|922337[0-1][0-9]{9}|92233720[0-2][0-9]{7}|922337203[0-5][0-9]{6}|9223372036[0-7][0-9]{5}|92233720368[0-4][0-9]{4}|922337203685[0-3][0-9]{3}|9223372036854[0-6][0-9]{2}|92233720368547[0-6][0-9]{1}|922337203685477[0-4])(?:[.][0-9]{1,3})?|9223372036854775(?:[.](?:(?:[0-7]|8)|(?:[0-7][0-9]{1}|80)|(?:[0-7][0-9]{2}|80[0-6]|807)))?)$" } ], "example": "USD -12.34", "description": "Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range." }, "PositiveMoneyInput": { "allOf": [ { "$ref": "#/components/schemas/MoneyInput" } ], "pattern": "^[A-Z]{3} (?=[0-9.]*[1-9])(?:0|[1-9][0-9]*)(?:[.][0-9]+)?$", "example": "USD 12.34", "description": "Exact Money text with an amount strictly greater than zero." }, "DatasetQueryRequest": { "oneOf": [ { "$ref": "#/components/schemas/AccountsDatasetQueryRequest" }, { "$ref": "#/components/schemas/BalancesDatasetQueryRequest" }, { "$ref": "#/components/schemas/AccountTermsDatasetQueryRequest" }, { "$ref": "#/components/schemas/TransactionsDatasetQueryRequest" }, { "$ref": "#/components/schemas/CoverageDatasetQueryRequest" }, { "$ref": "#/components/schemas/SpendingCategoriesDatasetQueryRequest" }, { "$ref": "#/components/schemas/MerchantsDatasetQueryRequest" }, { "$ref": "#/components/schemas/RecurringDatasetQueryRequest" }, { "$ref": "#/components/schemas/HoldingsDatasetQueryRequest" }, { "$ref": "#/components/schemas/InvestmentTransactionsDatasetQueryRequest" }, { "$ref": "#/components/schemas/BudgetsDatasetQueryRequest" }, { "$ref": "#/components/schemas/GoalsDatasetQueryRequest" }, { "$ref": "#/components/schemas/RulesDatasetQueryRequest" }, { "$ref": "#/components/schemas/ChangesDatasetQueryRequest" }, { "$ref": "#/components/schemas/ActionsDatasetQueryRequest" } ] }, "AccountsDatasetQueryRequest": { "description": "Query the accounts dataset.", "allOf": [ { "$ref": "#/components/schemas/CursorDatasetQueryRequest" }, { "properties": { "dataset": { "type": "string", "const": "accounts", "description": "Which declared dataset to query. `candor data list` names them." } } } ] }, "BalancesDatasetQueryRequest": { "description": "Query the balances dataset.", "allOf": [ { "$ref": "#/components/schemas/CursorDatasetQueryRequest" }, { "properties": { "dataset": { "type": "string", "const": "balances", "description": "Which declared dataset to query. `candor data list` names them." } } } ] }, "AccountTermsDatasetQueryRequest": { "description": "Query the effective account terms dataset.", "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "account_terms", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/AccountTermsDatasetQueryFilters" } } }, "TransactionsDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "transactions", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/TransactionDatasetQueryFilters" } } }, "CoverageDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "coverage", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/EmptyDatasetQueryFilters" } } }, "SpendingCategoriesDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "spending_categories", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/DateBoundedDatasetQueryFilters" } } }, "MerchantsDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "merchants", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/MerchantDatasetQueryFilters" } } }, "RecurringDatasetQueryRequest": { "description": "Query the recurring dataset.", "allOf": [ { "$ref": "#/components/schemas/CursorDatasetQueryRequest" }, { "properties": { "dataset": { "type": "string", "const": "recurring", "description": "Which declared dataset to query. `candor data list` names them." } } } ] }, "HoldingsDatasetQueryRequest": { "description": "Query the holdings dataset.", "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "holdings", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/HoldingsDatasetQueryFilters" } } }, "InvestmentTransactionsDatasetQueryRequest": { "description": "Query the investment transactions dataset.", "allOf": [ { "$ref": "#/components/schemas/CursorDatasetQueryRequest" }, { "properties": { "dataset": { "type": "string", "const": "investment_transactions", "description": "Which declared dataset to query. `candor data list` names them." } } } ] }, "BudgetsDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "budgets", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/BudgetDatasetQueryFilters" } } }, "GoalsDatasetQueryRequest": { "description": "Query the goals dataset.", "allOf": [ { "$ref": "#/components/schemas/CursorDatasetQueryRequest" }, { "properties": { "dataset": { "type": "string", "const": "goals", "description": "Which declared dataset to query. `candor data list` names them." } } } ] }, "RulesDatasetQueryRequest": { "description": "Query the rules dataset.", "allOf": [ { "$ref": "#/components/schemas/CursorDatasetQueryRequest" }, { "properties": { "dataset": { "type": "string", "const": "rules", "description": "Which declared dataset to query. `candor data list` names them." } } } ] }, "ChangesDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "changes", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/ChangesDatasetQueryFilters" } } }, "ActionsDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "const": "actions", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/ActionsDatasetQueryFilters" } } }, "CursorDatasetQueryRequest": { "type": "object", "additionalProperties": false, "required": [ "dataset" ], "properties": { "dataset": { "type": "string", "description": "Which declared dataset to query. `candor data list` names them." }, "filters": { "$ref": "#/components/schemas/CursorDatasetQueryFilters" } } }, "EmptyDatasetQueryFilters": { "type": "object", "additionalProperties": false }, "CursorDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "description": "Continue from pagination.next_cursor." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "AccountTermsDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "account_identity_id": { "type": "string", "minLength": 1, "description": "Restrict history caps to one durable account identity." }, "cursor": { "type": "string", "minLength": 1, "description": "Continue from the next_cursor returned by the previous account terms page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "DateBoundedDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "since": { "type": "string", "minLength": 1 }, "until": { "type": "string", "minLength": 1 } } }, "TransactionDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "since": { "type": "string", "minLength": 1 }, "source_account_id": { "type": "string", "minLength": 1, "description": "Restrict transactions to one visible account using the exact id returned by accounts.list. Omit this filter to return transactions across every visible account." }, "until": { "type": "string", "minLength": 1 } } }, "HoldingsDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "description": "Continue from pagination.next_cursor." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "source_account_id": { "type": "string", "minLength": 1, "description": "Restrict positions to one visible source account." } } }, "MerchantDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "merchant": { "type": "string", "minLength": 1 }, "since": { "type": "string", "minLength": 1 }, "until": { "type": "string", "minLength": 1 } } }, "BudgetDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "period": { "type": "string", "minLength": 1, "description": "The window this covers." } } }, "ChangesDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "account_identity_id": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "enum": [ "all", "spending", "income", "recurring", "account_terms" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "ActionsDatasetQueryFilters": { "type": "object", "additionalProperties": false, "properties": { "cursor": { "type": "string", "minLength": 1, "description": "Continue from pagination.next_cursor." }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "task_key": { "type": "string", "minLength": 1 } } }, "GoalCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "goal_key", "kind", "name" ], "anyOf": [ { "required": [ "approval_note" ] }, { "required": [ "approval_source" ] } ], "properties": { "approval_note": { "type": "string", "minLength": 1, "description": "What the user actually approved, in their terms. A goal is a commitment they made, so this records their decision rather than your inference from their spending." }, "approval_source": { "type": "string", "minLength": 1, "description": "Where that approval happened, such as the conversation or message it came from." }, "contribution_amount": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "contribution_cadence": { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly", "annual" ] }, "goal_key": { "type": "string", "minLength": 1, "description": "Stable identifier you choose and reuse. Later runs and progress records find the goal by this, so keep it durable and descriptive." }, "kind": { "type": "string", "enum": [ "sinking_fund", "debt_reduction", "reserve", "purchase", "income", "other" ], "description": "What sort of commitment this is, which decides how progress reads: a sinking fund accumulates, debt reduction pays down, a reserve is held rather than spent." }, "name": { "type": "string", "minLength": 1, "description": "What the user calls this goal. It appears in answers, so write it as they would say it rather than as a slug." }, "policy_notes": { "type": "string", "minLength": 1 }, "set_by": { "type": "string", "minLength": 1, "description": "Who set the goal, when it was not you acting alone." }, "target_amount": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "target_date": { "type": "string", "minLength": 1 } }, "description": "A durable commitment the user approved. Either approval_note or approval_source is required, because a goal nobody agreed to is a guess with a deadline attached." }, "GoalUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "goal_id" ], "anyOf": [ { "required": [ "approval_note" ] }, { "required": [ "approval_source" ] } ], "properties": { "approval_note": { "type": "string", "minLength": 1, "description": "What the user approved changing, in their terms." }, "approval_source": { "type": "string", "minLength": 1, "description": "Where the user's approval to change this goal was recorded." }, "contribution_amount": { "oneOf": [ { "$ref": "#/components/schemas/PositiveMoneyInput" }, { "type": "null" } ] }, "contribution_cadence": { "oneOf": [ { "type": "string", "enum": [ "weekly", "biweekly", "monthly", "quarterly", "annual" ] }, { "type": "null" } ] }, "goal_id": { "type": "string", "minLength": 1, "description": "The goal this concerns, as returned when it was created." }, "name": { "type": "string", "minLength": 1 }, "policy_notes": { "type": [ "string", "null" ], "minLength": 1 }, "set_by": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "paused", "completed" ] }, "target_amount": { "oneOf": [ { "$ref": "#/components/schemas/PositiveMoneyInput" }, { "type": "null" } ] }, "target_date": { "type": [ "string", "null" ], "minLength": 1 } }, "description": "Either approval_note or approval_source is required." }, "GoalArchiveRequest": { "type": "object", "additionalProperties": false, "required": [ "goal_id" ], "properties": { "goal_id": { "type": "string", "minLength": 1, "description": "The goal this concerns, as returned when it was created." } } }, "GoalProgressRequest": { "type": "object", "additionalProperties": false, "required": [ "amount", "goal_id", "kind" ], "properties": { "amount": { "$ref": "#/components/schemas/MoneyInput", "description": "Exact money as an uppercase ISO currency code, one space, then a signed decimal: `USD 100.00`. A bare `100.00` is rejected, and the number of decimal places has to match the currency." }, "goal_id": { "type": "string", "minLength": 1, "description": "The goal this progress belongs to, as returned when it was created." }, "kind": { "type": "string", "enum": [ "contribution", "withdrawal", "adjustment" ], "description": "Whether this event adds to the goal, takes from it, or corrects it. Withdrawals and adjustments net against observed progress, so the running total is a balance rather than a sum of deposits." }, "note": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "integer", "minimum": 1 } } }, "FinancialImpactBasisRef": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "const": "transaction", "description": "Reference a transaction." }, "id": { "type": "string", "minLength": 1, "description": "Transaction id supporting the impact." } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "const": "account", "description": "Reference a canonical account identity." }, "id": { "type": "string", "minLength": 1, "description": "Account identity id supporting the impact." } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "const": "recurring_item", "description": "Reference a recurring financial item." }, "id": { "type": "string", "minLength": 1, "description": "Recurring item id supporting the impact." } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "const": "goal", "description": "Reference a first-class financial goal." }, "id": { "type": "string", "minLength": 1, "description": "Goal id supporting the impact." } } }, { "type": "object", "additionalProperties": false, "required": [ "type", "id" ], "properties": { "type": { "const": "action", "description": "Reference a prior Candor action that records why it happened." }, "id": { "type": "string", "minLength": 1, "description": "Action id supporting the impact." } } } ], "description": "A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted." }, "FinancialImpactValue": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "kind", "gross_benefit" ], "properties": { "kind": { "const": "one_time", "description": "Treat this as one-time money." }, "gross_benefit": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "implementation_cost": { "$ref": "#/components/schemas/PositiveMoneyInput" } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "gross_benefit", "window_start", "window_end" ], "properties": { "kind": { "const": "bounded_total", "description": "Treat this as a total over one explicit window." }, "gross_benefit": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "implementation_cost": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "window_start": { "type": "string", "format": "date-time", "description": "Inclusive start of the value window." }, "window_end": { "type": "string", "format": "date-time", "description": "Inclusive end of the value window." } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "gross_benefit", "interval" ], "properties": { "kind": { "const": "recurring_rate", "description": "Treat this as a recurring money rate." }, "gross_benefit": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "implementation_cost": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "interval": { "type": "string", "enum": [ "monthly", "annual" ], "description": "Cadence of the recurring value." } } }, { "type": "object", "additionalProperties": false, "required": [ "kind", "duration", "unit" ], "properties": { "kind": { "const": "time", "description": "Treat this as time returned to the user." }, "duration": { "type": "string", "pattern": "^(?=.*[1-9])(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$", "description": "Positive exact decimal duration." }, "unit": { "type": "string", "enum": [ "minutes", "hours" ], "description": "Unit of the returned time." } } } ], "description": "Exact value without mixed units. Gross benefit and implementation cost remain separate; one-time, bounded, recurring, and time value never collapse into one headline number." }, "FinancialImpactGroundingProperties": { "type": "object", "properties": { "occurred_at": { "type": "string", "format": "date-time", "description": "When this happened. Omit only when it happened now." }, "basis_refs": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FinancialImpactBasisRef" }, "description": "Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead." }, "context_note_id": { "type": "string", "minLength": 1, "description": "A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence." } } }, "FinancialImpactGroundedEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundingProperties" } ], "anyOf": [ { "required": [ "basis_refs" ] }, { "required": [ "context_note_id" ] } ] }, "FinancialImpactCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "category", "benefit_summary" ], "anyOf": [ { "required": [ "basis_refs" ] }, { "required": [ "context_note_id" ] } ], "properties": { "category": { "type": "string", "enum": [ "money_recovered", "spending_reduced", "fees_or_interest_reduced", "income_or_yield_increased", "benefit_or_reward_captured", "tax_cost_reduced", "time_returned" ], "description": "The typed financial mechanism, not a merchant-specific label." }, "benefit_summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "How this could benefit the user, in plain language that remains useful when the current conversation is gone." }, "identified_at": { "type": "string", "format": "date-time", "description": "When the agent decided to act on the specific reviewed finding." }, "potential_value": { "$ref": "#/components/schemas/FinancialImpactValue", "description": "Defensible potential only. Omit it instead of inventing precision." }, "basis_refs": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/FinancialImpactBasisRef" }, "description": "Typed records supporting the identified opportunity. Omit only when context_note_id carries the reconstructable calculation and caveats instead." }, "context_note_id": { "type": "string", "minLength": 1, "description": "A note containing the reconstructable calculation, caveats, or external context for the identified opportunity. Use basis_refs instead when canonical Candor records directly support the claim." } } }, "FinancialImpactActionTakenEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundedEvent" }, { "type": "object", "required": [ "type", "action_summary" ], "properties": { "type": { "const": "action_taken", "description": "Record a concrete step taken for this impact." }, "action_summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "What the agent or user actually did." } } } ], "unevaluatedProperties": false }, "FinancialImpactValueRecordedEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundedEvent" }, { "type": "object", "required": [ "type", "state", "value_basis", "value" ], "properties": { "type": { "const": "value_recorded", "description": "Record an observed or realized value." }, "state": { "type": "string", "enum": [ "outcome_observed", "realized" ], "description": "Whether the value is observed or has actually landed." }, "value_basis": { "type": "string", "enum": [ "observed", "agent_attested", "user_confirmed", "evidence_verified" ], "description": "Who or what supports the value. Agent attestation is accepted and remains visibly distinct from independent verification." }, "value": { "$ref": "#/components/schemas/FinancialImpactValue" }, "supersedes_event_id": { "type": "string", "minLength": 1, "description": "The active value event this corrects. Its history remains, but it leaves current aggregates." } } } ], "unevaluatedProperties": false }, "FinancialImpactDetailsRevisedEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundedEvent" }, { "type": "object", "required": [ "type" ], "anyOf": [ { "required": [ "category" ] }, { "required": [ "benefit_summary" ] } ], "properties": { "type": { "const": "details_revised", "description": "Correct the impact category or benefit summary." }, "category": { "type": "string", "enum": [ "money_recovered", "spending_reduced", "fees_or_interest_reduced", "income_or_yield_increased", "benefit_or_reward_captured", "tax_cost_reduced", "time_returned" ], "description": "Corrected typed financial mechanism for the same impact." }, "benefit_summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Corrected user-readable benefit for the same impact." } } } ], "unevaluatedProperties": false }, "FinancialImpactPotentialRevisedEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundedEvent" }, { "type": "object", "required": [ "type", "potential_value" ], "properties": { "type": { "const": "potential_revised", "description": "Replace or remove the active potential value." }, "potential_value": { "description": "New potential value, or null to remove it.", "oneOf": [ { "$ref": "#/components/schemas/FinancialImpactValue" }, { "type": "null" } ] }, "supersedes_event_id": { "type": "string", "minLength": 1, "description": "The exact active potential-value event_id returned by the impact view. Required when replacing or removing an active potential; omit only when adding the first potential value." } } } ], "unevaluatedProperties": false }, "FinancialImpactClosedEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundingProperties" }, { "type": "object", "required": [ "type", "reason_summary" ], "properties": { "type": { "const": "closed_without_value", "description": "Close work that ended without financial value." }, "reason_summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why this ended without realized value." } } } ], "unevaluatedProperties": false }, "FinancialImpactRevertedEvent": { "allOf": [ { "$ref": "#/components/schemas/FinancialImpactGroundingProperties" }, { "type": "object", "required": [ "type", "reason_summary", "reverses_event_id" ], "properties": { "type": { "const": "reverted", "description": "Reverse an active observed or realized value." }, "reason_summary": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Why the observed or realized value is no longer valid." }, "reverses_event_id": { "type": "string", "minLength": 1, "description": "The active observed- or realized-value event removed from current aggregates." } } } ], "unevaluatedProperties": false }, "FinancialImpactRecordRequest": { "type": "object", "additionalProperties": false, "required": [ "impact_id", "event" ], "properties": { "impact_id": { "type": "string", "minLength": 1, "description": "The stable impact returned at discovery. Reuse it so discovery, action, outcome, and correction remain one history." }, "event": { "description": "Typed event to append to the existing impact history.", "oneOf": [ { "$ref": "#/components/schemas/FinancialImpactActionTakenEvent" }, { "$ref": "#/components/schemas/FinancialImpactValueRecordedEvent" }, { "$ref": "#/components/schemas/FinancialImpactDetailsRevisedEvent" }, { "$ref": "#/components/schemas/FinancialImpactPotentialRevisedEvent" }, { "$ref": "#/components/schemas/FinancialImpactClosedEvent" }, { "$ref": "#/components/schemas/FinancialImpactRevertedEvent" } ] } } }, "WorkspaceOpenAcknowledgeRequest": { "type": "object", "additionalProperties": false, "required": [ "checkpoint" ], "properties": { "checkpoint": { "type": "string", "minLength": 1, "description": "The opening checkpoint you are acknowledging, so the next opening starts after what you actually read." } } }, "NoteAbout": { "type": "object", "additionalProperties": false, "required": [ "resource", "id" ], "description": "Links the note to the exact record it is about, so a later run can find it from the record instead of by searching note text.", "properties": { "resource": { "type": "string", "minLength": 1, "description": "Resource name, such as transactions or accounts." }, "id": { "type": "string", "minLength": 1, "description": "Canonical id of that record, pasted whole." } } }, "NoteCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "body_markdown" ], "description": "Your own durable memory. A note is how a finding survives the end of this session, so write it before you answer.", "properties": { "body_markdown": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "For a re-check note, carry all four parts: the promise or the outcome you are waiting on, the exact baseline including ids and money strings, the literal recipe to run on revisit, and what each plausible outcome would mean. Paste exact values rather than summarizing them; a truncated handle cannot be resolved later." }, "about": { "$ref": "#/components/schemas/NoteAbout" }, "revisit_at": { "type": "string", "format": "date-time", "description": "When the outcome becomes observable, not when you wrote the note. This is what surfaces the note in the workspace opening once due. Without it the note is still listed and still retrievable, but nothing brings it back to you at the right moment, so a promise depending on it is one you have to remember unaided." } } }, "NoteUpdateRequest": { "type": "object", "additionalProperties": false, "required": [ "note_id" ], "anyOf": [ { "required": [ "body_markdown" ] }, { "required": [ "about" ] }, { "required": [ "revisit_at" ] } ], "description": "Revise a note in place, typically on revisit when the outcome moved but did not finish. Resolve it instead once the outcome is settled.", "properties": { "note_id": { "type": "string", "minLength": 1, "description": "The note this concerns." }, "body_markdown": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Replaces the body. On revisit, carry forward the new baseline rather than dropping what the last run observed." }, "about": { "description": "Replaces the resource this note concerns. Null removes the link; omitting the field preserves it.", "oneOf": [ { "$ref": "#/components/schemas/NoteAbout" }, { "type": "null" } ] }, "revisit_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Reschedule to the next time the outcome could be observable. Null clears it, which stops the note surfacing when due." } } }, "NoteIdRequest": { "type": "object", "additionalProperties": false, "required": [ "note_id" ], "properties": { "note_id": { "type": "string", "minLength": 1, "description": "The note this concerns." } } }, "InterpretationRuleCreateRequest": { "$ref": "#/components/schemas/NormalizationInterpretationRuleCreateRequest" }, "NormalizationInterpretationRuleCreateRequest": { "type": "object", "additionalProperties": false, "required": [ "name", "family", "target", "authority", "selector", "effect", "basis" ], "properties": { "name": { "type": "string", "description": "What this rule is for, in the user's terms. It appears when explaining why a transaction reads the way it does." }, "family": { "type": "string", "enum": [ "normalization" ], "description": "What the rule governs. Normalization is the only family today." }, "target": { "type": "string", "enum": [ "transaction_fields" ], "description": "What the rule changes." }, "authority": { "type": "string", "enum": [ "agent_verified", "user_approved" ], "description": "Where the rule's meaning came from. `user_approved` records that the user said so; `agent_verified` records that you established it from evidence and can show the basis." }, "selector": { "description": "What the rule matches: one exact transaction, or a criteria set that reaches future ones. Inspect a preview before applying, since a broad selector reaches far.", "oneOf": [ { "$ref": "#/components/schemas/TransactionRecordRuleSelector" }, { "$ref": "#/components/schemas/TransactionMatchRuleSelector" } ] }, "effect": { "description": "The field changes the rule applies where it matches.", "$ref": "#/components/schemas/SetTransactionFieldsRuleEffect" }, "basis": { "description": "The evidence behind the rule, so a later run can judge whether it still holds.", "$ref": "#/components/schemas/InterpretationRuleBasis" }, "auto_apply": { "type": "string", "enum": [ "none", "future" ] }, "priority": { "type": "number" }, "created_by": { "type": "string" } } }, "InterpretationRuleBasis": { "description": "The evidence behind the rule, so a later run can judge whether it still holds.", "type": "object", "additionalProperties": false, "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Why this rule is correct, in one line a later run can weigh. Not approval and not evidence — the transaction ids carry that." }, "transaction_ids": { "type": "array", "items": { "type": "string" } } } }, "TransactionRecordRuleSelector": { "type": "object", "additionalProperties": false, "required": [ "kind", "transaction_id" ], "properties": { "kind": { "type": "string", "enum": [ "transaction_record" ], "description": "Selects one exact record, and nothing it resembles." }, "transaction_id": { "type": "string", "description": "The canonical transaction this rule applies to." } } }, "TransactionMatchRuleSelector": { "type": "object", "additionalProperties": false, "required": [ "kind", "criteria" ], "properties": { "kind": { "type": "string", "enum": [ "transaction_match" ], "description": "Selects every transaction the criteria match, including ones that arrive later." }, "criteria": { "description": "What a transaction must look like for this rule to reach it. Inspect a preview before applying: a broad criteria set reaches further than the records you looked at.", "type": "object", "additionalProperties": false, "properties": { "currency": { "type": "string", "description": "Three-letter uppercase ISO code, such as USD." }, "current_category": { "type": "string" }, "description_contains": { "type": "string" }, "direction": { "type": "string", "enum": [ "inflow", "outflow" ] }, "has_tag": { "type": "string" }, "max_amount": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "merchant_name_contains": { "type": "string" }, "merchant_name_equals": { "type": "string" }, "min_amount": { "$ref": "#/components/schemas/PositiveMoneyInput" }, "source_classification_contains": { "type": "string" }, "source_classification_equals": { "type": "string" }, "review_status": { "type": "string", "enum": [ "unreviewed", "needs_review", "reviewed", "ignored" ] }, "since": { "type": "string" }, "source_account_id": { "type": "string", "description": "The account this belongs to." }, "until": { "type": "string" } } } } }, "SetTransactionFieldsRuleEffect": { "description": "The field changes the rule applies where it matches.", "type": "object", "additionalProperties": false, "required": [ "kind", "actions" ], "properties": { "kind": { "type": "string", "enum": [ "set_transaction_fields" ], "description": "The sort of change this rule makes." }, "actions": { "type": "object", "additionalProperties": false, "description": "The field changes to apply. Everything omitted is left as the source recorded it.", "properties": { "add_tags": { "type": "array", "items": { "type": "string" } }, "remove_tags": { "type": "array", "items": { "type": "string" } }, "set_cashflow_role": { "type": "string", "enum": [ "income", "expense", "transfer", "debt_payment", "refund", "unknown" ] }, "set_category": { "type": "string" }, "set_label": { "type": "string" }, "set_review_status": { "type": "string", "enum": [ "unreviewed", "needs_review", "reviewed", "ignored" ] } } } } }, "Money": { "type": "string", "maxLength": 32, "oneOf": [ { "pattern": "^(?:CLP|JPY|KRW) (?!-0$)-?(?:(?:0|[1-9][0-9]{0,17}|[1-8][0-9]{18}|9[0-1][0-9]{17}|92[0-1][0-9]{16}|922[0-2][0-9]{15}|9223[0-2][0-9]{14}|92233[0-6][0-9]{13}|922337[0-1][0-9]{12}|92233720[0-2][0-9]{10}|922337203[0-5][0-9]{9}|9223372036[0-7][0-9]{8}|92233720368[0-4][0-9]{7}|922337203685[0-3][0-9]{6}|9223372036854[0-6][0-9]{5}|92233720368547[0-6][0-9]{4}|922337203685477[0-4][0-9]{3}|9223372036854775[0-7][0-9]{2}|922337203685477580[0-6])|9223372036854775807)$" }, { "pattern": "^(?:AUD|BRL|CAD|CHF|CNY|EUR|GBP|HKD|INR|MXN|NZD|SGD|USD) (?!-0[.]0{2}$)-?(?:(?:0|[1-9][0-9]{0,15}|[1-8][0-9]{16}|9[0-1][0-9]{15}|92[0-1][0-9]{14}|922[0-2][0-9]{13}|9223[0-2][0-9]{12}|92233[0-6][0-9]{11}|922337[0-1][0-9]{10}|92233720[0-2][0-9]{8}|922337203[0-5][0-9]{7}|9223372036[0-7][0-9]{6}|92233720368[0-4][0-9]{5}|922337203685[0-3][0-9]{4}|9223372036854[0-6][0-9]{3}|92233720368547[0-6][0-9]{2}|922337203685477[0-4][0-9]{1}|9223372036854775[0-7])[.][0-9]{2}|92233720368547758[.](?:(?:0[0-6]|07)))$" }, { "pattern": "^(?:BHD|KWD|OMR) (?!-0[.]0{3}$)-?(?:(?:0|[1-9][0-9]{0,14}|[1-8][0-9]{15}|9[0-1][0-9]{14}|92[0-1][0-9]{13}|922[0-2][0-9]{12}|9223[0-2][0-9]{11}|92233[0-6][0-9]{10}|922337[0-1][0-9]{9}|92233720[0-2][0-9]{7}|922337203[0-5][0-9]{6}|9223372036[0-7][0-9]{5}|92233720368[0-4][0-9]{4}|922337203685[0-3][0-9]{3}|9223372036854[0-6][0-9]{2}|92233720368547[0-6][0-9]{1}|922337203685477[0-4])[.][0-9]{3}|9223372036854775[.](?:(?:[0-7][0-9]{2}|80[0-6]|807)))$" } ], "example": "USD -12.34", "description": "Canonical Money text returned as one self-contained JSON string with the currency's exact decimal places." }, "AccountPolicyRequest": { "type": "object", "required": [ "account_identity_id", "include_in_workspace", "approval_note" ], "description": "Changes which accounts every later calculation sees. Whether an account belongs in the picture is the user's call, not an inference from the data, so carry their actual decision here.", "properties": { "account_identity_id": { "type": "string", "description": "The durable account identity this concerns, which survives a reconnected source connection." }, "include_in_workspace": { "type": "boolean", "description": "Excluding an account removes it from balances, net position, and cashflow everywhere, not just from one view." }, "role": { "type": "string", "enum": [ "operating_cash", "cash_reserve", "health_savings", "retirement", "investment", "credit_card", "debt", "unknown" ], "description": "Overrides the role derived from account type. Set it only when the user tells you the derived role is wrong, since roles drive runway and reserve math." }, "approval_note": { "type": "string", "description": "What the user actually approved, in their terms, recorded so a later run can tell an approved decision from an inferred one. Not a restatement of the change itself." }, "approval_source": { "type": "string", "description": "Where that approval happened, such as the conversation or message it came from." }, "set_by": { "type": "string", "description": "Who made the change, when it was not you acting alone." } } }, "AccountTermAssertionRequest": { "type": "object", "required": [ "account_identity_id", "field", "value", "approval_note" ], "description": "A user's approved account-term correction or supplement. It remains separate from source observations so provider evidence stays intact and can become effective again when the assertion expires or is reverted.", "properties": { "account_identity_id": { "type": "string", "description": "The durable account identity this concerns, which survives a reconnected source connection." }, "field": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?![$_])[\\x20-\\x7E]+$", "description": "The canonical account-term field, such as apr.purchase, minimum_payment, promo_expiry_date, or apy." }, "value": { "description": "The typed exact value the user approved for this field.", "oneOf": [ { "type": "object", "required": [ "kind", "amount" ], "properties": { "kind": { "type": "string", "const": "money", "description": "Selects an exact Money value." }, "amount": { "$ref": "#/components/schemas/MoneyInput" } } }, { "type": "object", "required": [ "kind", "decimal" ], "properties": { "kind": { "type": "string", "const": "percentage", "description": "Selects an exact non-negative percentage." }, "decimal": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$", "description": "Exact non-negative percentage text, such as 24.99." } } }, { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "const": "date", "description": "Selects an ISO calendar date." }, "value": { "type": "string", "format": "date", "description": "The approved ISO calendar date." } } }, { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "const": "boolean", "description": "Selects a true or false account term." }, "value": { "type": "boolean", "description": "The approved true or false value." } } }, { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "const": "string", "description": "Selects a non-empty textual term." }, "value": { "type": "string", "minLength": 1, "description": "The approved textual term." } } } ] }, "effective_from": { "type": "string", "format": "date-time", "description": "When this approved assertion begins applying." }, "effective_through": { "type": "string", "format": "date-time", "description": "When this approved assertion stops applying." }, "approval_note": { "type": "string", "minLength": 1, "description": "What the user actually approved, in their terms." }, "approval_source": { "type": "string", "description": "Where that approval happened, such as the conversation or message it came from." }, "set_by": { "type": "string", "description": "Who made the change, when it was not you acting alone." } } }, "ManualAccountPreviewRequest": { "type": "object", "required": [ "display_name", "type", "currency", "closing_balance", "as_of" ], "properties": { "display_name": { "type": "string", "description": "What the user calls this account." }, "institution_name": { "type": "string" }, "type": { "type": "string", "description": "What kind of account this is, which decides how its balance reads." }, "subtype": { "type": "string" }, "currency": { "type": "string", "description": "Three-letter uppercase ISO code, such as USD." }, "closing_balance": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "The balance at `as_of`, as a plain decimal in the account's curren cy." }, "as_of": { "type": "string", "format": "date", "description": "When this balance was observed." }, "set_by": { "type": "string" } } }, "ManualTransactionPreviewRequest": { "type": "object", "required": [ "source_account_id", "amount", "date", "description" ], "properties": { "source_account_id": { "type": "string", "description": "The account this belongs to." }, "amount": { "type": "string", "pattern": "^-?(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$", "description": "Exact money, as a plain signed decimal in the account's currency." }, "date": { "type": "string", "format": "date", "description": "When the activity posted, as an ISO calendar date." }, "description": { "type": "string", "description": "The source description, kept as written so the record stays evidence." }, "merchant_name": { "type": "string" }, "category": { "type": "string", "description": "The effective category this line governs." }, "reference_number": { "type": "string" }, "set_by": { "type": "string" } } }, "RecurringPolicyRequest": { "type": "object", "required": [ "recurring_item_id", "status", "approval_note" ], "description": "Durable judgment about a detected recurring series, which then overrides detection until reverted.", "properties": { "recurring_item_id": { "type": "string", "description": "The recurring item this concerns." }, "merchant_name": { "type": "string" }, "cadence": { "type": "string" }, "amount_estimate": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$" }, "category": { "type": "string", "description": "The effective category this line governs." }, "status": { "type": "string", "enum": [ "active", "stopped", "changed", "not_recurring" ], "description": "stopped means a real series ended. not_recurring means the series was never real and suppresses the false candidate durably. Do not use stopped for a misdetection, or the workspace keeps expecting a charge that was never a subscription." }, "approval_note": { "type": "string", "description": "What the user actually approved, in their terms. Whether a charge is wanted encodes their values, so this records their decision rather than your inference." }, "approval_source": { "type": "string", "description": "Where that approval happened, such as the conversation or message it came from." }, "set_by": { "type": "string", "description": "Who made the change, when it was not you acting alone." } } }, "TransactionSplitRequest": { "type": "object", "required": [ "transaction_id", "lines", "approval_note" ], "description": "Reallocates one transaction across categories. This is an overlay: the source evidence and its total are never changed, so the split is fully reversible.", "properties": { "transaction_id": { "type": "string", "description": "The canonical transaction this concerns." }, "lines": { "type": "array", "minItems": 2, "maxItems": 25, "description": "Every line replaces the previous allocation as a set. Amounts are unsigned and strictly greater than zero, and must account for the whole transaction, so a partial split is rejected rather than silently leaving a remainder. Drop a category rather than giving it a zero line.", "items": { "type": "object", "required": [ "amount", "category" ], "properties": { "amount": { "type": "string", "pattern": "^(?=[0-9.]*[1-9])[0-9]+(?:\\.[0-9]+)?$", "description": "Unsigned and greater than zero." }, "category": { "type": "string", "description": "The effective category this line governs." }, "label": { "type": "string" }, "note": { "type": "string" } } } }, "approval_note": { "type": "string", "description": "What the user actually approved, in their terms. How a charge should be divided reflects what it was for, which they know and you infer." }, "approval_source": { "type": "string", "description": "Where that approval happened, such as the conversation or message it came from." }, "set_by": { "type": "string", "description": "Who made the change, when it was not you acting alone." } } }, "DataFreshness": { "type": "object", "additionalProperties": false, "required": [ "coverage" ], "properties": { "balances_last_synced_at": { "type": "string" }, "coverage": { "type": "string", "enum": [ "complete", "partial", "stale", "unavailable" ] }, "holdings_last_synced_at": { "type": "string" }, "transactions_last_synced_at": { "type": "string" } } }, "ResponseEnvelope": { "type": "object", "additionalProperties": false, "required": [ "schema_version", "generated_at", "request_id", "status", "summary", "warnings", "errors", "next_actions", "data" ], "properties": { "schema_version": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "success", "partial_success", "action_required", "error" ] }, "summary": { "type": "string", "description": "Concise agent-facing explanation of the outcome." }, "user_message": { "type": "string", "description": "Optional concise user-safe message the calling agent may adapt." }, "data_freshness": { "$ref": "#/components/schemas/DataFreshness" }, "warnings": { "type": "array", "items": { "type": "object" } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/AgentError" } }, "next_actions": { "type": "array", "items": { "$ref": "#/components/schemas/AgentAction" } }, "action": { "$ref": "#/components/schemas/WorkspaceAction" }, "data": { "type": "object" } } }, "WorkspaceAction": { "type": "object", "additionalProperties": false, "required": [ "id", "operation", "reason", "root_action_id", "status", "created_at" ], "properties": { "id": { "type": "string" }, "operation": { "type": "string" }, "reason": { "type": "string" }, "root_action_id": { "type": "string" }, "parent_action_id": { "type": "string" }, "task_key": { "type": "string" }, "status": { "type": "string", "enum": [ "started", "succeeded", "refused", "failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" } } }, "AgentAction": { "type": "object", "required": [ "intent", "command", "args", "shell" ], "properties": { "intent": { "type": "string" }, "command": { "type": "string" }, "args": { "type": "object", "additionalProperties": true }, "shell": { "type": "string" } } }, "AgentError": { "type": "object", "required": [ "code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "expires_at": { "type": "string" }, "idempotency_key": { "type": "string", "minLength": 16, "maxLength": 128, "pattern": "^[\\x20-\\x7E]+$", "description": "Stable key to reuse when retrying this identical logical operation." }, "message": { "type": "string" }, "recovery_url": { "type": "string", "format": "uri" }, "required_capability": { "type": "string" }, "retry_after_seconds": { "type": "integer", "minimum": 1, "description": "Machine-actionable delay before retrying the identical logical operation." }, "retryable": { "type": "boolean" }, "suggested_command": { "type": "string" } } }, "CuratedImportManifest": { "type": "object", "required": [ "account", "period" ], "allOf": [ { "if": { "required": [ "holdings_scope" ], "properties": { "holdings_scope": { "const": "complete" } } }, "then": { "properties": { "holdings": { "items": { "allOf": [ { "not": { "required": [ "estimate_quantity" ] } }, { "anyOf": [ { "required": [ "quantity" ], "properties": { "quantity": { "type": "string" } } }, { "required": [ "value" ], "properties": { "value": { "type": "string" } } } ] } ] } } } } } ], "properties": { "source_kind": { "type": "string" }, "source_provider": { "type": "string", "enum": [ "agent_curated" ], "description": "Curated imports always use the agent-curated ingestion channel; native providers use separate source adapters." }, "source_id": { "type": "string" }, "file_name": { "type": "string" }, "file_sha256": { "type": "string" }, "authority": { "type": "string", "description": "Evidence authority, not transport. statement_reconciled means the broker or source evidence was faithfully transcribed and reconciled; partial or unreconciled evidence uses agent_curated_unreconciled. manual_correction is a reviewed human correction.", "enum": [ "live_provider", "statement_reconciled", "agent_curated_unreconciled", "manual_correction", "external_claim_unverified" ] }, "account": { "type": "object", "required": [ "display_name", "type", "currency" ], "properties": { "institution_name": { "type": "string" }, "display_name": { "type": "string", "description": "What the user calls this account." }, "mask": { "type": "string" }, "type": { "type": "string", "description": "What kind of account this is, which decides how its balance reads." }, "subtype": { "type": "string" }, "currency": { "type": "string", "description": "Three-letter uppercase ISO code, such as USD." }, "source_account_id": { "type": "string", "description": "Existing Candor source account id these records belong to. Use it to add, update, or remove holdings in a particular manual account; transaction imports require it either here or via the CLI --source-account flag." }, "source_external_account_id": { "type": "string" }, "account_identity_key": { "type": "string" } }, "description": "The account these records belong to." }, "period": { "type": "object", "required": [ "start", "end" ], "properties": { "start": { "type": "string", "description": "First day the period covers, as an ISO calendar date." }, "end": { "type": "string", "description": "Last day the period covers, as an ISO calendar date." }, "complete_statement_period": { "type": "boolean" } }, "description": "The window this covers." }, "balances": { "type": "object", "properties": { "opening": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$" }, "closing": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Exact observed account balance. For a manual investment account, use the displayed portfolio total so it can be reconciled to submitted holding values and included in balance history and net worth." }, "as_of": { "type": "string", "description": "When this balance was observed." } } }, "holdings_scope": { "type": "string", "enum": [ "incremental", "complete" ], "default": "incremental", "description": "Incremental leaves omitted positions unchanged. Complete is allowed only for an existing agent-curated source_account_id with a dated closing balance and same-time holding rows that each include exact quantity or value; preview then turns every omitted active position into an explicit reversible removal." }, "holdings": { "type": "array", "maxItems": 1000, "items": { "oneOf": [ { "type": "object", "not": { "required": [ "holding_id" ] }, "anyOf": [ { "required": [ "quantity" ] }, { "required": [ "value" ] }, { "allOf": [ { "required": [ "row_key" ] }, { "anyOf": [ { "required": [ "as_of" ] }, { "required": [ "cost_basis" ] }, { "required": [ "market" ] }, { "required": [ "name" ] }, { "required": [ "price" ] }, { "required": [ "price_source_locator" ] }, { "required": [ "quantity_source" ] }, { "required": [ "security_id" ] }, { "required": [ "symbol" ] }, { "required": [ "type" ] } ] } ] } ], "allOf": [ { "if": { "required": [ "quantity_source" ], "properties": { "quantity_source": { "const": "derived" } } }, "then": { "required": [ "type", "quantity", "price", "value", "price_source_locator", "as_of" ], "properties": { "type": { "enum": [ "stock", "equity", "etf", "fund", "mutual fund" ], "type": "string" }, "quantity": { "type": "string" }, "price": { "type": "string" }, "value": { "type": "string" }, "price_source_locator": { "type": "string" }, "as_of": { "type": "string" } } } }, { "if": { "required": [ "estimate_quantity" ], "properties": { "estimate_quantity": { "const": true } } }, "then": { "required": [ "symbol", "market", "type", "value" ], "properties": { "market": { "const": "US" }, "type": { "enum": [ "stock", "equity", "etf" ], "type": "string" }, "symbol": { "type": "string" }, "value": { "type": "string" } }, "not": { "anyOf": [ { "required": [ "quantity" ] }, { "required": [ "quantity_source" ] }, { "required": [ "price" ] }, { "required": [ "price_source_locator" ] } ] } } } ], "properties": { "row_key": { "type": "string", "minLength": 1, "description": "Stable source-local key. Reuse it for later observations of the same position in this account." }, "operation": { "type": "string", "const": "upsert", "description": "Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value." }, "security_id": { "type": [ "string", "null" ], "description": "Source security identifier when one is visible." }, "symbol": { "type": [ "string", "null" ], "description": "Ticker or other short source symbol when visible." }, "market": { "type": [ "string", "null" ], "enum": [ "US", null ], "description": "Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency." }, "name": { "type": "string", "description": "Source-displayed name of the position." }, "type": { "type": [ "string", "null" ], "description": "Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0." }, "estimate_quantity": { "type": "boolean", "const": true, "description": "Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions." }, "quantity": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention." }, "quantity_source": { "type": [ "string", "null" ], "enum": [ "observed", "derived", null ], "description": "Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of." }, "price": { "type": [ "string", "null" ], "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived." }, "price_source_locator": { "type": [ "string", "null" ], "description": "Evidence locator for the exact price used to derive quantity. Required with quantity_source derived." }, "value": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict." }, "currency": { "type": "string", "description": "Three-letter uppercase ISO code; defaults to the account currency." }, "cost_basis": { "type": [ "string", "null" ], "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict." }, "as_of": { "type": [ "string", "null" ], "description": "Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today." }, "source_locator": { "type": "string", "description": "Agent-readable pointer back to the evidence, such as screenshot number and row." }, "confidence": { "type": "number", "description": "Optional extraction confidence from zero to one. Omission is reported as unknown; it does not change source authority and is not persisted on the canonical holding." } } }, { "type": "object", "additionalProperties": false, "required": [ "operation" ], "anyOf": [ { "required": [ "holding_id" ] }, { "required": [ "row_key" ] } ], "properties": { "operation": { "type": "string", "const": "remove", "description": "Remove this holding from the current state of its manual account. Historical balance snapshots remain intact, prior holding state is preserved for revert, and no investment trade or cash movement is created." }, "holding_id": { "type": "string", "description": "Exact canonical holding id. It must be active, agent-curated, and belong to this manifest's account." }, "row_key": { "type": "string", "minLength": 1, "description": "Stable source-local identity returned by holdings reads. It may target the agent-curated holding when holding_id is omitted." }, "source_locator": { "type": "string", "description": "Agent-readable pointer to the evidence or reviewed correction." } } } ] } }, "transactions": { "type": "array", "items": { "type": "object", "required": [ "date", "amount", "description" ], "properties": { "row_key": { "type": "string" }, "date": { "type": "string", "description": "When the activity posted, as an ISO calendar date." }, "amount": { "type": "string", "pattern": "^-?[0-9]+(?:\\.[0-9]+)?$", "description": "Exact money, as a plain signed decimal in the account's currency." }, "currency": { "type": "string", "description": "Three-letter uppercase ISO code, such as USD." }, "description": { "type": "string", "description": "The source description, kept as written so the record stays evidence." }, "merchant_name": { "type": "string" }, "category": { "type": "string", "description": "The effective category this line governs." }, "pending": { "type": "boolean" }, "source_locator": { "type": "string" }, "confidence": { "type": "number" }, "reference_number": { "type": "string" } } } }, "terms": { "type": "array", "maxItems": 100, "description": "Source-backed account terms normalized into canonical typed fields. Omit row_key only when one logical value exists for the field; the fallback identity is then derived from terms_kind and field.", "items": { "type": "object", "required": [ "terms_kind", "field", "value" ], "properties": { "row_key": { "type": "string", "description": "Stable identity for this logical term across later imports." }, "terms_kind": { "type": "string", "enum": [ "credit_card", "mortgage", "student_loan", "deposit", "loan" ], "description": "Canonical shape of the account terms." }, "field": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^(?![$_])[\\x20-\\x7E]+$", "description": "Consistent Candor field name across connected accounts, approved records, and imports, such as apr.purchase, minimum_payment, payment_due_date, or apy." }, "value": { "description": "Typed value observed for this field.", "oneOf": [ { "type": "object", "required": [ "kind", "amount" ], "properties": { "kind": { "type": "string", "const": "money", "description": "Selects an exact Money value." }, "amount": { "$ref": "#/components/schemas/MoneyInput" } } }, { "type": "object", "required": [ "kind", "decimal" ], "properties": { "kind": { "type": "string", "const": "percentage", "description": "Selects a non-negative percentage value." }, "decimal": { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)(?:\\.[0-9]+)?$", "description": "Exact percentage points as a decimal string, such as 19.25 for 19.25 percent." } } }, { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "const": "date", "description": "Selects an ISO calendar date." }, "value": { "type": "string", "format": "date", "description": "Exact ISO calendar date for the term." } } }, { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "const": "boolean", "description": "Selects a true-or-false term value." }, "value": { "type": "boolean", "description": "Observed true-or-false value." } } }, { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "const": "string", "description": "Selects a bounded text term value." }, "value": { "type": "string", "minLength": 1, "description": "Observed text value for the term." } } } ] }, "observed_at": { "type": "string", "format": "date-time", "description": "When the term was observed at its source." }, "effective_from": { "type": "string", "format": "date-time", "description": "When the observed term begins to apply." }, "effective_through": { "type": "string", "format": "date-time", "description": "Optional last instant when the observed term applies." }, "source_locator": { "type": "string", "description": "Human-auditable location in the source, such as a statement page or disclosure section." } } } }, "curation": { "type": "object", "properties": { "agent": { "type": "string" }, "method": { "type": "string" }, "notes": { "type": "string" } } } } } } } }