{ "openapi": "3.1.0", "info": { "title": "Evenbead Ledger API", "version": "0.1.0", "description": "Agent-native double-entry ledger. Every operation here is also an MCP tool at POST /mcp. Amounts are integer cents. Every write needs an Idempotency-Key; agent writes need X-Agent-Model. Errors carry a stable error.type." }, "servers": [ { "url": "https://api.evenbead.com", "description": "API and MCP" }, { "url": "https://app.evenbead.com", "description": "Same API on the web app's origin" } ], "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Liveness check", "tags": [ "meta" ], "security": [], "responses": { "200": { "description": "Up", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This OpenAPI 3.1 document", "tags": [ "meta" ], "security": [], "responses": { "200": { "description": "OpenAPI document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/mcp": { "post": { "operationId": "mcp", "summary": "MCP server (Streamable HTTP, stateless JSON-RPC). Same tools as this API; auth via the same Bearer key.", "tags": [ "meta" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notification accepted" }, "400": { "description": "Protocol error", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/companies": { "post": { "operationId": "createCompany", "summary": "Create a company (tenant) with its owner user and owner API key. Operator bootstrap token required.", "tags": [ "admin" ], "security": [ { "bootstrap": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "owner_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." }, "starter_chart": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart)." }, "periods": { "type": "boolean", "description": "Create this fiscal year's and the next one's monthly periods (default true; false for a custom calendar)" } }, "required": [ "name", "owner_name" ], "additionalProperties": false }, "example": { "name": "Riverbend Bakery LLC", "owner_name": "Sam Rivera", "starter_chart": "general" } } } }, "responses": { "201": { "description": "Created, with the starter chart applied and this fiscal year's and the next one's monthly periods", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" }, "owner": { "$ref": "#/components/schemas/User" }, "api_key": { "$ref": "#/components/schemas/IssuedKey" }, "setup": { "$ref": "#/components/schemas/CompanySetup" } }, "required": [ "company", "owner", "api_key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/operator/companies/{id}/plan": { "get": { "operationId": "getCompanyPlan", "summary": "A company's plan (ADR-0009) and the API rate limit it gives. Operator token only.", "tags": [ "admin" ], "security": [ { "bootstrap": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "responses": { "200": { "description": "Plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." }, "rate_limit_rpm": { "type": [ "integer", "null" ] } }, "required": [ "company_id", "name", "plan", "rate_limit_rpm" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "setCompanyPlan", "summary": "Set a company's plan (ADR-0009); its keys' and agents' rate limits follow on the next request. Audited in the company's log as the operator. Operator token only.", "tags": [ "admin" ], "security": [ { "bootstrap": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Not needed: this write sets a value, so repeating it leaves the same state." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "plan", "reason" ], "additionalProperties": false }, "example": { "plan": "advanced", "reason": "upgraded at the customer's request" } } } }, "responses": { "200": { "description": "Plan set", "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." }, "previous_plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." }, "changed": { "type": "boolean" }, "rate_limit_rpm": { "type": [ "integer", "null" ] } }, "required": [ "company_id", "name", "plan", "previous_plan", "changed", "rate_limit_rpm" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/company": { "get": { "operationId": "getCompany", "summary": "The caller's company", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Company", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" } }, "required": [ "company" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/me": { "get": { "operationId": "getMe", "summary": "Who the caller is: principal type, name, role, scopes, company", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Caller", "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_type": { "type": "string", "enum": [ "user", "agent" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "key_prefix": { "type": "string" }, "company": { "$ref": "#/components/schemas/Company" }, "firm": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "member_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "role": { "type": "string" }, "firm_agent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "id", "name" ] }, "session": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "idle_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "absolute_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id" ] }, "key": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the company plan's limit)." }, "rotated_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "expires_at" ] }, "rate_limit": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." }, "key_rpm": { "type": "integer", "description": "This credential's budget (requests per minute)" }, "company_agent_rpm": { "type": "integer", "description": "All agents of this company together" } }, "required": [ "plan", "key_rpm", "company_agent_rpm" ] } }, "required": [ "principal_type", "id", "name", "role", "scopes", "key_prefix", "company" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/company/kill-switch": { "post": { "operationId": "setKillSwitch", "summary": "Suspend or resume ALL agent writes for this company", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suspended": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "suspended", "reason" ], "additionalProperties": false }, "example": { "suspended": true, "reason": "agent misbehaving" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" } }, "required": [ "company" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/users": { "post": { "operationId": "createUser", "summary": "Create a human user", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "enum": [ "owner", "cpa", "accountant", "staff" ] } }, "required": [ "name", "role" ], "additionalProperties": false }, "example": { "name": "Dana Okafor, CPA", "role": "cpa" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listUsers", "summary": "People in this company (names for the audit view)", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Users", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "$ref": "#/components/schemas/User" } } }, "required": [ "users" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/agents": { "post": { "operationId": "createAgent", "summary": "Register an agent with scopes and a posting threshold", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "posting_threshold_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "owner_user_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "name", "scopes", "posting_threshold_cents" ], "additionalProperties": false }, "example": { "name": "categorizer", "scopes": [ "read", "propose" ], "posting_threshold_cents": 50000 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" } }, "required": [ "agent" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listAgents", "summary": "Registered agents with scopes, thresholds and revocation", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } } }, "required": [ "agents" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/agents/{id}/revoke": { "post": { "operationId": "revokeAgent", "summary": "Revoke an agent; all its keys stop working on the next request", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "decommissioned" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/Agent" } }, "required": [ "agent" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/keys": { "post": { "operationId": "createKey", "summary": "Mint an API key for a user or agent (secret returned once, stored hashed). Keys expire: people's after 365 days, agents' after 30 days by default (at most 90).", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_type": { "type": "string", "enum": [ "user", "agent" ] }, "user_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Lifetime in days. Default: 365 for a person's key, 30 for an agent's (at most 90)." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the company plan's limit)." } }, "required": [ "principal_type", "scopes" ], "additionalProperties": false }, "example": { "principal_type": "agent", "agent_id": "00000000-0000-4000-8000-000000000000", "scopes": [ "read", "propose" ], "expires_in_days": 30, "rate_limit_rpm": 60 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewApiKey" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listKeys", "summary": "API keys (never secrets): expiry, last use, rate budget, rotation, status. Admins see the company's keys; others their own.", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_ended", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } }, "required": [ "keys" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/keys/{id}": { "get": { "operationId": "getKey", "summary": "One API key (admins: any in the company; others: their own)", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Key", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/keys/{id}/rotate": { "post": { "operationId": "rotateKey", "summary": "Rotate a live key (the company's admins, or the key's own holder: an agent can rotate the key it calls with). The successor has the same principal and scopes and a fresh lifetime; the old key keeps working for the overlap window (default 24 h, at most 7 days, 0 = at once). The new secret is returned once.", "tags": [ "admin" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 604800 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Lifetime in days. Default: 365 for a person's key, 30 for an agent's (at most 90)." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "Change the budget (the company's admins only); omitted: unchanged." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "overlap_seconds": 3600, "reason": "monthly rotation" } } } }, "responses": { "201": { "description": "Rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/IssuedKey" }, "key": { "$ref": "#/components/schemas/ApiKey" }, "previous": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "api_key", "key", "previous" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/owner-invites/claim": { "post": { "operationId": "claimOwnerInvite", "summary": "The owner claims a company an accounting firm created: send the invitation (ebi_...) as the Bearer token. Returns the owner's key once; the firm never sees it. Single use; void after 14 days or once the company revokes the firm's access.", "tags": [ "admin" ], "security": [ { "ownerInvite": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Lifetime in days. Default: 365 for a person's key, 30 for an agent's (at most 90)." } }, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Claimed", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" }, "owner": { "$ref": "#/components/schemas/User" }, "api_key": { "$ref": "#/components/schemas/IssuedKey" } }, "required": [ "company", "owner", "api_key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/keys/{id}/revoke": { "post": { "operationId": "revokeKey", "summary": "Revoke one API key, effective on the next request", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "rotated" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/ApiKey" } }, "required": [ "api_key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/accounts": { "post": { "operationId": "createAccount", "summary": "Add an account to the chart of accounts", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "income", "expense" ] }, "subtype": { "type": "string", "minLength": 1, "maxLength": 60 }, "parent_code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "control": { "type": "string", "enum": [ "ar", "ap" ], "description": "Make it an AR (asset) or AP (liability) control account; fixed at creation" } }, "required": [ "code", "name", "type" ], "additionalProperties": false }, "example": { "code": "6100", "name": "Rent", "type": "expense" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" } }, "required": [ "account" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listAccounts", "summary": "List the chart of accounts, with the default income and expense accounts for new documents", "tags": [ "ledger" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "include_balances", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "defaults": { "$ref": "#/components/schemas/DefaultAccounts" } }, "required": [ "accounts", "defaults" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/accounts/{code}/update": { "post": { "operationId": "updateAccount", "summary": "Rename an account, or deactivate or reactivate it. Codes, types and the AR/AP designation never change; accounts are never deleted. Deactivation is refused (account_protected) for an AR/AP control account, a bank account's ledger account, an active sales-tax rate's payable account, an active item's account, a default account and a parent with active sub-accounts. Audited; dry_run previews.", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S(.*\\S)?$" }, "active": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "dry_run": { "type": "boolean" } }, "additionalProperties": false }, "example": { "name": "Rent & Coworking" } } } }, "responses": { "200": { "description": "Updated (or, with dry_run, what it would be)", "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "$ref": "#/components/schemas/Account" }, "dry_run": { "type": "boolean" } }, "required": [ "account" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/accounts/defaults": { "post": { "operationId": "setDefaultAccounts", "summary": "Set the default income account (invoices, credit memos, sales receipts, estimates) and expense account (bills, vendor credits) new document lines start on; null clears one. Audited.", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Not needed: this write sets a value, so repeating it leaves the same state." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "income": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "expense": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, "additionalProperties": false }, "example": { "income": "4000", "expense": "7900" } } } }, "responses": { "200": { "description": "The defaults", "content": { "application/json": { "schema": { "type": "object", "properties": { "defaults": { "$ref": "#/components/schemas/DefaultAccounts" } }, "required": [ "defaults" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/starter-charts": { "get": { "operationId": "listStarterCharts", "summary": "Starter charts of accounts a company can begin with (each account, and the default income and expense accounts)", "tags": [ "ledger" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "starter_charts": { "type": "array", "items": { "$ref": "#/components/schemas/StarterChart" } } }, "required": [ "starter_charts" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/accounts/starter-chart": { "post": { "operationId": "applyStarterChart", "summary": "Apply a starter chart to a company whose chart of accounts is still empty (otherwise chart_not_empty). Every account is audited, then the template; the defaults are set. dry_run previews.", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart)." }, "dry_run": { "type": "boolean" } }, "required": [ "template" ], "additionalProperties": false }, "example": { "template": "general" } } } }, "responses": { "200": { "description": "Dry run: what would be created", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart)." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "defaults": { "$ref": "#/components/schemas/DefaultAccounts" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } }, "dry_run": { "type": "boolean" } }, "required": [ "template", "accounts", "defaults", "bank_accounts" ] } } } }, "201": { "description": "Applied", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart)." }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "defaults": { "$ref": "#/components/schemas/DefaultAccounts" }, "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } }, "dry_run": { "type": "boolean" } }, "required": [ "template", "accounts", "defaults", "bank_accounts" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/periods": { "post": { "operationId": "createPeriod", "summary": "Create an accounting period", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, "required": [ "start_date", "end_date" ], "additionalProperties": false }, "example": { "start_date": "2026-09-01", "end_date": "2026-09-30" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/Period" } }, "required": [ "period" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listPeriods", "summary": "List periods and their lock status", "tags": [ "ledger" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Periods", "content": { "application/json": { "schema": { "type": "object", "properties": { "periods": { "type": "array", "items": { "$ref": "#/components/schemas/Period" } } }, "required": [ "periods" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/periods/{id}/status": { "post": { "operationId": "setPeriodStatus", "summary": "Lock or unlock a period (reopening a hard lock needs a human and a reason)", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "soft_locked", "hard_locked" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "status" ], "additionalProperties": false }, "example": { "status": "hard_locked", "reason": "August closed" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/Period" } }, "required": [ "period" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/reports/trial-balance": { "get": { "operationId": "getTrialBalance", "summary": "Trial balance as of a date", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Trial balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialBalance" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/transactions": { "get": { "operationId": "searchTransactions", "summary": "Search posted journal entries", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "account", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "min_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, { "name": "max_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/JournalEntry" } } }, "required": [ "entries" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/journal-entries/{id}": { "get": { "operationId": "getJournalEntry", "summary": "One posted journal entry. Posted entries are immutable: there is no update or delete; reverse instead.", "tags": [ "ledger" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Entry", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "$ref": "#/components/schemas/JournalEntry" } }, "required": [ "entry" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/journal-entries/propose": { "post": { "operationId": "proposeJournalEntry", "summary": "Propose a journal entry. Agents: auto-posts within policy, otherwise queues for approval. dry_run=true previews without writing.", "tags": [ "ledger" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string", "maxLength": 500 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DraftLine" }, "minItems": 1, "maxItems": 200 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "entry_date", "lines" ], "additionalProperties": false }, "example": { "entry_date": "2026-09-03", "memo": "Office supplies", "lines": [ { "account": "6300", "debit_cents": 4299 }, { "account": "1000", "credit_cents": 4299 } ] } } } }, "responses": { "200": { "description": "Dry run: the exact entry, policy verdict and affected balances; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/journal-entries/{id}/reverse": { "post": { "operationId": "reverseJournalEntry", "summary": "Correct a posted entry by posting its exact reversal", "tags": [ "ledger" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string", "maxLength": 500 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "memo": "Wrong vendor" } } } }, "responses": { "201": { "description": "Reversal posted", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry": { "$ref": "#/components/schemas/JournalEntry" } }, "required": [ "entry" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/proposals": { "get": { "operationId": "listProposals", "summary": "The proposal queue", "tags": [ "governance" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "auto_posted", "approved", "rejected" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Proposals", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/Proposal" } } }, "required": [ "proposals" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/proposals/{id}/approve": { "post": { "operationId": "approveProposal", "summary": "Approve a pending proposal and post it (human, or a supervisor agent other than the requester)", "tags": [ "governance" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Approved and posted (for a document or payment proposal, the document or payment is created too)", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal": { "$ref": "#/components/schemas/Proposal" }, "entry": { "$ref": "#/components/schemas/JournalEntry" }, "document": { "$ref": "#/components/schemas/Document" }, "payment": { "$ref": "#/components/schemas/Payment" } }, "required": [ "proposal", "entry" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/proposals/{id}/reject": { "post": { "operationId": "rejectProposal", "summary": "Reject a pending proposal with a reason", "tags": [ "governance" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "This is equipment, not supplies" } } } }, "responses": { "200": { "description": "Rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposal": { "$ref": "#/components/schemas/Proposal" } }, "required": [ "proposal" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/classes": { "post": { "operationId": "createClass", "summary": "Create a class (reporting dimension for journal lines)", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^\\S(.{0,58}\\S)?$", "description": "Class name (reporting dimension)." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Catering" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "class": { "$ref": "#/components/schemas/Class" } }, "required": [ "class" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listClasses", "summary": "List classes", "tags": [ "ledger" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Classes", "content": { "application/json": { "schema": { "type": "object", "properties": { "classes": { "type": "array", "items": { "$ref": "#/components/schemas/Class" } } }, "required": [ "classes" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/profit-and-loss": { "get": { "operationId": "getProfitAndLoss", "summary": "Profit and loss for a date range, by account; optionally one class; accrual (default) or cash basis", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "class", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\S(.{0,58}\\S)?$", "description": "Class name (reporting dimension)." } }, { "name": "basis", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "accrual", "cash" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "P&L", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfitAndLoss" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/balance-sheet": { "get": { "operationId": "getBalanceSheet", "summary": "Balance sheet as of a date, with current-year earnings and prior-year retained earnings rolled up", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Balance sheet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSheet" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/general-ledger": { "get": { "operationId": "getGeneralLedger", "summary": "General ledger detail: every line in a date range by account, with opening, running and closing balances", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "account", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "General ledger", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralLedger" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/exports/tax-trial-balance": { "get": { "operationId": "exportTaxTrialBalance", "summary": "Year-to-date trial balance for tax preparation in the documented generic CSV (evenbead-tb-generic/1). Recorded in the audit log.", "tags": [ "exports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Tax trial balance (CSV by default with format=csv; JSON adds control totals)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxTrialBalance" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-accounts": { "post": { "operationId": "createBankAccount", "summary": "Register a bank or card account, linked to its ledger account", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "checking", "savings", "credit_card", "other" ] }, "ledger_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "institution": { "type": "string", "minLength": 1, "maxLength": 100 }, "mask": { "type": "string", "pattern": "^[0-9A-Za-z]{2,4}$" }, "csv_profile": { "$ref": "#/components/schemas/CsvProfile" } }, "required": [ "name", "kind", "ledger_account" ], "additionalProperties": false }, "example": { "name": "Operating Checking", "kind": "checking", "ledger_account": "1000", "mask": "4821" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_account": { "$ref": "#/components/schemas/BankAccount" } }, "required": [ "bank_account" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listBankAccounts", "summary": "Bank accounts with ledger balance, line counts by state and reconciliation status", "tags": [ "banking" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Bank accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankAccount" } } }, "required": [ "bank_accounts" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-accounts/{id}/update": { "post": { "operationId": "updateBankAccount", "summary": "Correct a bank or card account's name, institution or last digits (null clears institution or mask). The ledger account and kind never change. Audited.", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "institution": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "mask": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z]{2,4}$" } }, "additionalProperties": false }, "example": { "name": "Operating Checking", "institution": "First Community Bank", "mask": "4821" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_account": { "$ref": "#/components/schemas/BankAccount" } }, "required": [ "bank_account" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-accounts/{id}": { "get": { "operationId": "getBankAccount", "summary": "One bank account with its import history", "tags": [ "banking" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Bank account", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_account": { "$ref": "#/components/schemas/BankAccount" }, "imports": { "type": "array", "items": { "$ref": "#/components/schemas/BankImport" } } }, "required": [ "bank_account", "imports" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-accounts/{id}/imports": { "post": { "operationId": "importBankStatement", "summary": "Import an OFX/QFX or CSV statement. Lines dedupe on FITID or a content hash, so re-importing is a no-op. dry_run previews.", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "ofx", "qfx", "csv" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 240000, "description": "The file's text." }, "filename": { "type": "string", "minLength": 1, "maxLength": 200 }, "csv_profile": { "$ref": "#/components/schemas/CsvProfile" }, "dry_run": { "type": "boolean" } }, "required": [ "format", "content" ], "additionalProperties": false }, "example": { "format": "csv", "filename": "sept.csv", "content": "Date,Description,Amount\n09/01/2026,RENT,-2800.00\n", "csv_profile": { "date": "Date", "date_format": "MM/DD/YYYY", "description": "Description", "amount": "Amount" } } } } }, "responses": { "200": { "description": "Dry run: parsed lines and which are duplicates; nothing written", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "const": true }, "lines_total": { "type": "integer" }, "lines_new": { "type": "integer" }, "lines_duplicate": { "type": "integer" }, "lines": { "type": "array" } }, "required": [ "dry_run", "lines_total", "lines_new", "lines_duplicate" ] } } } }, "201": { "description": "Imported", "content": { "application/json": { "schema": { "type": "object", "properties": { "import": { "$ref": "#/components/schemas/BankImport" }, "new_lines": { "type": "array", "items": { "$ref": "#/components/schemas/BankLine" } }, "skipped_zero_amount": { "type": "integer" } }, "required": [ "import", "new_lines" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-accounts/{id}/auto-match": { "post": { "operationId": "autoMatchBankLines", "summary": "Match unmatched lines to existing entries (same amount, date within the window) and pair transfers between own accounts. Ambiguous cases are left for a human.", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "window_days": { "type": "integer", "minimum": 0, "maximum": 10 }, "transfers": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "additionalProperties": false }, "example": { "window_days": 3 } } } }, "responses": { "200": { "description": "Result (also for dry runs)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoMatchResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-lines": { "get": { "operationId": "listBankLines", "summary": "Bank lines with their state; unmatched lines carry the first matching rule's suggestion", "tags": [ "banking" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "bank_account_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unmatched", "proposed", "matched", "categorized", "excluded" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Bank lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "$ref": "#/components/schemas/BankLine" } } }, "required": [ "lines" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-lines/{id}/categorize": { "post": { "operationId": "categorizeBankLine", "summary": "Categorize an unmatched line into an account. Same governance as propose: agents auto-post within policy, otherwise it queues for approval; humans post. dry_run previews.", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "class": { "type": "string", "pattern": "^\\S(.{0,58}\\S)?$", "description": "Class name (reporting dimension)." }, "memo": { "type": "string", "maxLength": 500 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "dry_run": { "type": "boolean" }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "account" ], "additionalProperties": false }, "example": { "account": "6100", "confidence": 0.97 } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeResult" } } } }, "201": { "description": "Posted and linked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeResult" } } } }, "202": { "description": "Queued for approval; the line is 'proposed' until decided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProposeResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-lines/{id}/match": { "post": { "operationId": "matchBankLine", "summary": "Match an unmatched line to an existing posted entry that moves the bank's ledger account by exactly the line amount", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "entry_id" ], "additionalProperties": false }, "example": { "entry_id": "00000000-0000-4000-8000-000000000000" } } } }, "responses": { "200": { "description": "Matched", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_line": { "$ref": "#/components/schemas/BankLine" } }, "required": [ "bank_line" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-lines/{id}/unmatch": { "post": { "operationId": "unmatchBankLine", "summary": "Undo a match (or release a line whose entry was reversed). Refused once the entry is cleared in a finished reconciliation.", "tags": [ "banking" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "matched to the wrong deposit" } } } }, "responses": { "200": { "description": "Unmatched", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_line": { "$ref": "#/components/schemas/BankLine" } }, "required": [ "bank_line" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/bank-lines/{id}/exclude": { "post": { "operationId": "excludeBankLine", "summary": "Exclude an unmatched line (not a business transaction, e.g. a duplicate the bank sent)", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "duplicate sent by the bank" } } } }, "responses": { "200": { "description": "Excluded", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_line": { "$ref": "#/components/schemas/BankLine" } }, "required": [ "bank_line" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-lines/{id}/restore": { "post": { "operationId": "restoreBankLine", "summary": "Restore an excluded line to unmatched", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_line": { "$ref": "#/components/schemas/BankLine" } }, "required": [ "bank_line" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-rules": { "post": { "operationId": "createBankRule", "summary": "Create a categorization rule (payee contains / amount range → account, by priority). Rules never post: the rules-engine agent applies them through categorize.", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "priority": { "type": "integer", "minimum": 0, "maximum": 100000 }, "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "payee_contains": { "type": "string", "minLength": 1, "maxLength": 100 }, "direction": { "type": "string", "enum": [ "in", "out", "any" ] }, "amount_min_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "amount_max_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "class": { "type": "string", "pattern": "^\\S(.{0,58}\\S)?$", "description": "Class name (reporting dimension)." }, "memo": { "type": "string", "maxLength": 200 } }, "required": [ "name", "priority", "account" ], "additionalProperties": false }, "example": { "name": "Rent", "priority": 10, "payee_contains": "OAKWOOD PROPERTIES", "direction": "out", "account": "6100" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/BankRule" } }, "required": [ "rule" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listBankRules", "summary": "Rules in evaluation order (priority, then age)", "tags": [ "banking" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "$ref": "#/components/schemas/BankRule" } } }, "required": [ "rules" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-rules/{id}/deactivate": { "post": { "operationId": "deactivateBankRule", "summary": "Deactivate a rule (rules are never edited or deleted)", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "landlord changed" } } } }, "responses": { "200": { "description": "Deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": { "$ref": "#/components/schemas/BankRule" } }, "required": [ "rule" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-accounts/{id}/reconciliations": { "post": { "operationId": "startReconciliation", "summary": "Start reconciling a statement. The beginning balance is the last finished statement's ending balance. auto_clear pre-clears lines the bank already showed.", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "statement_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "statement_ending_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "auto_clear": { "type": "boolean" } }, "required": [ "statement_date", "statement_ending_balance_cents" ], "additionalProperties": false }, "example": { "statement_date": "2026-09-30", "statement_ending_balance_cents": 1234500, "auto_clear": true } } } }, "responses": { "201": { "description": "Started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDetail" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/reconciliations": { "get": { "operationId": "listReconciliations", "summary": "Reconciliations, newest statement first", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "bank_account_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Reconciliations", "content": { "application/json": { "schema": { "type": "object", "properties": { "reconciliations": { "type": "array", "items": { "$ref": "#/components/schemas/Reconciliation" } } }, "required": [ "reconciliations" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reconciliations/{id}": { "get": { "operationId": "getReconciliation", "summary": "A reconciliation with its cleared lines and (while in progress) the uncleared candidates", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Reconciliation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDetail" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reconciliations/{id}/update": { "post": { "operationId": "updateReconciliation", "summary": "Clear or unclear ledger lines, or correct the statement date/ending balance, while in progress", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "clear": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 2000 }, "unclear": { "type": "array", "items": { "type": "integer", "minimum": 1 }, "maxItems": 2000 }, "statement_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "statement_ending_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "additionalProperties": false }, "example": { "clear": [ 1, 2 ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDetail" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/reconciliations/{id}/finish": { "post": { "operationId": "finishReconciliation", "summary": "Finish: only at zero difference. Finished reconciliations are immutable and audited by the database.", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Finished", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationDetail" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/reconciliations/{id}/cancel": { "post": { "operationId": "cancelReconciliation", "summary": "Discard an in-progress reconciliation (finished ones can never be removed)", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "wrong statement" } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "reconciliation": { "$ref": "#/components/schemas/Reconciliation" } }, "required": [ "reconciliation" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/reconciliations/{id}/report": { "get": { "operationId": "getReconciliationReport", "summary": "Reconciliation report: cleared deposits and payments, uncleared items, book vs statement tie-out", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationReport" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/audit/verify": { "get": { "operationId": "verifyAudit", "summary": "Verify this company's audit hash chain", "tags": [ "audit" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerdict" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/audit/events": { "get": { "operationId": "listAuditEvents", "summary": "Audit events in chain order (or newest first), filtered by actor, agent, model or action", "tags": [ "audit" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "after_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "before_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ] } }, { "name": "actor_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user", "agent", "system" ] } }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "model", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } }, "required": [ "events" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/audit/export": { "get": { "operationId": "exportAudit", "summary": "Full audit chain export for offline verification (JSON fields as the exact hashed text)", "tags": [ "audit" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Export", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object" } } }, "required": [ "events" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/company/fiscal-year": { "post": { "operationId": "setFiscalYear", "summary": "Set the fiscal year start month (refused while any period is hard-locked). Applies to reports, year-to-date and fiscal-year period locks.", "tags": [ "admin" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_month": { "type": "integer", "minimum": 1, "maximum": 12 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "start_month" ], "additionalProperties": false }, "example": { "start_month": 7, "reason": "June year-end" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" } }, "required": [ "company" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/fiscal-years/periods": { "post": { "operationId": "createFiscalYearPeriods", "summary": "Create the monthly periods of a fiscal year that do not exist yet (named by the year it ends)", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "minimum": 1900, "maximum": 2999 } }, "required": [ "fiscal_year" ], "additionalProperties": false }, "example": { "fiscal_year": 2027 } } } }, "responses": { "201": { "description": "Periods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearPeriods" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/fiscal-years/status": { "post": { "operationId": "setFiscalYearStatus", "summary": "Lock (or reopen) every period of a fiscal year; each change is audited (reopening a hard lock needs a person and a reason)", "tags": [ "ledger" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fiscal_year": { "type": "integer", "minimum": 1900, "maximum": 2999 }, "status": { "type": "string", "enum": [ "open", "soft_locked", "hard_locked" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "fiscal_year", "status" ], "additionalProperties": false }, "example": { "fiscal_year": 2026, "status": "hard_locked", "reason": "FY2026 closed and filed" } } } }, "responses": { "200": { "description": "Periods", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiscalYearPeriods" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/contacts": { "post": { "operationId": "createContact", "summary": "Add a customer or vendor", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "customer", "vendor" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S(.*\\S)?$" }, "email": { "type": "string", "maxLength": 254, "pattern": "^[^@\\s]+@[^@\\s]+$" }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "is_1099": { "type": "boolean", "description": "Vendors only: this vendor gets a 1099" }, "tax_id": { "type": "string", "pattern": "^(\\d{3}-?\\d{2}-?\\d{4}|\\d{2}-?\\d{7}|\\d{3} \\d{2} \\d{4}|\\d{2} \\d{7})$", "description": "The vendor's SSN or EIN (9 digits; dashes allowed). Write-only: Evenbead keeps only the last four digits and never returns the number." } }, "required": [ "kind", "name" ], "additionalProperties": false }, "example": { "kind": "customer", "name": "Henderson Catering", "terms_days": 30 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" } }, "required": [ "contact" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" }, "get": { "operationId": "listContacts", "summary": "Customers and vendors with open and overdue balances", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "customer", "vendor" ] } }, { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Contacts", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } } }, "required": [ "contacts" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/contacts/{id}": { "get": { "operationId": "getContact", "summary": "A customer or vendor with their documents and payments", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Contact", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "contact", "documents", "payments" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/contacts/{id}/update": { "post": { "operationId": "updateContact", "summary": "Rename, change email or terms, or (de)activate a customer or vendor; for vendors, the 1099 flag and the tax ID (only its last four digits are kept)", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S(.*\\S)?$" }, "email": { "type": [ "string", "null" ], "maxLength": 254, "pattern": "^[^@\\s]+@[^@\\s]+$" }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "active": { "type": "boolean" }, "is_1099": { "type": "boolean", "description": "Vendors only: this vendor gets a 1099" }, "tax_id": { "type": [ "string", "null" ], "pattern": "^(\\d{3}-?\\d{2}-?\\d{4}|\\d{2}-?\\d{7}|\\d{3} \\d{2} \\d{4}|\\d{2} \\d{7})$", "description": "The vendor's SSN or EIN (9 digits; dashes allowed). Write-only: Evenbead keeps only the last four digits and never returns the number. null forgets it." } }, "additionalProperties": false }, "example": { "terms_days": 15 } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" } }, "required": [ "contact" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/items": { "post": { "operationId": "createItem", "summary": "Add a product or service with default accounts and prices", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\S(.*\\S)?$" }, "kind": { "type": "string", "enum": [ "service", "non_inventory" ] }, "description": { "type": "string", "maxLength": 500 }, "sales_price_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "purchase_cost_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "income_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "expense_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "taxable": { "type": "boolean", "description": "Lines with this item are taxable by default" } }, "required": [ "name", "kind" ], "additionalProperties": false }, "example": { "name": "Wedding cake, 3 tier", "kind": "non_inventory", "sales_price_cents": 45000, "income_account": "4100" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Item" } }, "required": [ "item" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listItems", "summary": "Products and services", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Items", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" } } }, "required": [ "items" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/invoices": { "post": { "operationId": "createInvoice", "summary": "Create and post an invoice (Dr AR, Cr income per line). Agents: auto-posts within policy, otherwise queues for approval. dry_run previews.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The customer" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Vendor invoice no., PO no." }, "memo": { "type": "string", "maxLength": 500 }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "AR/AP control account (default: the first active one)" }, "tax_rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Sales-tax rate for the taxable lines (adds a tax line on the rate's payable account)" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 199 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id", "doc_date", "lines" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "doc_date": "2026-09-15", "memo": "Rehearsal dinner", "lines": [ { "description": "Dessert table", "account": "4100", "quantity": 1, "unit_price_cents": 85000 } ] } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/credit-memos": { "post": { "operationId": "createCreditMemo", "summary": "Create and post a credit memo for a customer (Dr income, Cr AR); apply it to invoices with /v1/documents/{id}/apply", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The customer" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Vendor invoice no., PO no." }, "memo": { "type": "string", "maxLength": 500 }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "AR/AP control account (default: the first active one)" }, "tax_rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Sales-tax rate for the taxable lines (adds a tax line on the rate's payable account)" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 199 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id", "doc_date", "lines" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "doc_date": "2026-09-15", "memo": "Rehearsal dinner", "lines": [ { "description": "Dessert table", "account": "4100", "quantity": 1, "unit_price_cents": 85000 } ] } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bills": { "post": { "operationId": "createBill", "summary": "Record and post a vendor bill (Dr expense per line, Cr AP). Same governance as invoices; dry_run previews.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The vendor" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Vendor invoice no., PO no." }, "memo": { "type": "string", "maxLength": 500 }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "AR/AP control account (default: the first active one)" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 199 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id", "doc_date", "lines" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "doc_date": "2026-09-15", "memo": "Rehearsal dinner", "lines": [ { "description": "Dessert table", "account": "5000", "quantity": 1, "unit_price_cents": 85000 } ] } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/vendor-credits": { "post": { "operationId": "createVendorCredit", "summary": "Record a vendor credit (Dr AP, Cr expense); apply it to bills with /v1/documents/{id}/apply", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The vendor" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Vendor invoice no., PO no." }, "memo": { "type": "string", "maxLength": 500 }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "AR/AP control account (default: the first active one)" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 199 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id", "doc_date", "lines" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "doc_date": "2026-09-15", "memo": "Rehearsal dinner", "lines": [ { "description": "Dessert table", "account": "5000", "quantity": 1, "unit_price_cents": 85000 } ] } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/documents": { "get": { "operationId": "listDocuments", "summary": "Invoices, credit memos, bills, vendor credits, sales receipts, refunds, expenses, checks and transfers with open balance and status", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "invoice", "credit_memo", "bill", "vendor_credit", "sales_receipt", "refund", "vendor_refund", "expense", "check", "transfer" ] } }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sales", "purchases", "spending" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "partial", "paid", "applied", "void", "overdue", "unpaid" ] } }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Documents, newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentSummary" } } }, "required": [ "documents" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/documents/{id}": { "get": { "operationId": "getDocument", "summary": "One document with its lines and the payments and credits applied to (or from) it", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Document", "content": { "application/json": { "schema": { "type": "object", "properties": { "document": { "$ref": "#/components/schemas/Document" } }, "required": [ "document" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/documents/{id}/void": { "post": { "operationId": "voidDocument", "summary": "Void a document by posting the exact reversal of its entry. Invoices/bills need any payments or credits voided first.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "void_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "dry_run": { "type": "boolean" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Issued to the wrong customer" } } } }, "responses": { "200": { "description": "Voided (or the dry-run preview)", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "document": { "$ref": "#/components/schemas/Document" }, "entry": { "$ref": "#/components/schemas/JournalEntry" } }, "required": [ "document" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/documents/{id}/apply": { "post": { "operationId": "applyCredit", "summary": "Apply a credit memo or vendor credit to open invoices or bills of the same customer or vendor", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "document_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "document_id", "amount_cents" ], "additionalProperties": false } }, "applied_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "dry_run": { "type": "boolean" } }, "required": [ "applications" ], "additionalProperties": false }, "example": { "applications": [ { "document_id": "00000000-0000-4000-8000-000000000000", "amount_cents": 2500 } ] } } } }, "responses": { "200": { "description": "Applied (or the dry-run preview)", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "document": { "$ref": "#/components/schemas/Document" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } }, "required": [ "document" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/payments/received": { "post": { "operationId": "receivePayment", "summary": "Record a customer payment applied to invoices (Dr bank, Cr AR), optionally from an unmatched bank deposit line (bank_line_id), which it categorizes. Same governance as propose.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "payment_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Defaults to the bank line's date" }, "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Bank, cash, undeposited-funds or card account (defaults to the bank line's account)" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The whole payment (default: the applications). Anything above the applications stays unapplied: credit on account (deposit, overpayment), applied later or refunded." }, "applications": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "type": "object", "properties": { "document_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "document_id", "amount_cents" ], "additionalProperties": false } }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "AR/AP control account for a payment with no applications (default: the first active one)" }, "bank_line_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "An unmatched bank line this payment is (same amount; deposit for received, withdrawal/charge for made)" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Check no., remittance id" }, "memo": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "payment_date": "2026-09-20", "account": "1000", "applications": [ { "document_id": "00000000-0000-4000-8000-000000000000", "amount_cents": 85000 } ], "reference": "CHK 1042" } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Recorded (and the bank line categorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval (the bank line is 'proposed' until decided)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/payments/made": { "post": { "operationId": "payBills", "summary": "Pay vendor bills (Dr AP, Cr bank or card), optionally from an unmatched bank or card line (bank_line_id). Same governance as propose.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "payment_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Defaults to the bank line's date" }, "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Bank, cash, undeposited-funds or card account (defaults to the bank line's account)" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "The whole payment (default: the applications). Anything above the applications stays unapplied: credit on account (deposit, overpayment), applied later or refunded." }, "applications": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "type": "object", "properties": { "document_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "document_id", "amount_cents" ], "additionalProperties": false } }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "AR/AP control account for a payment with no applications (default: the first active one)" }, "bank_line_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "An unmatched bank line this payment is (same amount; deposit for received, withdrawal/charge for made)" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Check no., remittance id" }, "memo": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "payment_date": "2026-09-20", "account": "1000", "applications": [ { "document_id": "00000000-0000-4000-8000-000000000000", "amount_cents": 85000 } ], "reference": "CHK 1042" } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Recorded (and the bank line categorized)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval (the bank line is 'proposed' until decided)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/payments": { "get": { "operationId": "listPayments", "summary": "Payments received and made, newest first (unapplied=true: only those with credit on account)", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "received", "made" ] } }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "unapplied", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Payments", "content": { "application/json": { "schema": { "type": "object", "properties": { "payments": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } }, "required": [ "payments" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/payments/{id}": { "get": { "operationId": "getPayment", "summary": "One payment with its applications", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "$ref": "#/components/schemas/Payment" } }, "required": [ "payment" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/payments/{id}/void": { "post": { "operationId": "voidPayment", "summary": "Void a payment: posts the exact reversal, releases its applications (documents reopen) and its bank line", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "void_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "dry_run": { "type": "boolean" } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Check bounced" } } } }, "responses": { "200": { "description": "Voided (or the dry-run preview)", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/Payment" }, "entry": { "$ref": "#/components/schemas/JournalEntry" } }, "required": [ "payment" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/reports/ar-aging": { "get": { "operationId": "getArAging", "summary": "Accounts receivable aging as of a date: open documents by days past due (current, 1-30, 31-60, 61-90, 90+), with the control-account tie-out", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Aging", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgingReport" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/ap-aging": { "get": { "operationId": "getApAging", "summary": "Accounts payable aging as of a date: open documents by days past due (current, 1-30, 31-60, 61-90, 90+), with the control-account tie-out", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Aging", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgingReport" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reconciliations/{id}/undo": { "post": { "operationId": "undoReconciliation", "summary": "Undo the latest finished reconciliation of a bank account (audited; refused while a period containing or after its statement is locked)", "tags": [ "reconciliation" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "Statement balance entered wrong" } } } }, "responses": { "200": { "description": "Undone", "content": { "application/json": { "schema": { "type": "object", "properties": { "reconciliation": { "$ref": "#/components/schemas/Reconciliation" } }, "required": [ "reconciliation" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/sessions": { "post": { "operationId": "createSession", "summary": "Open a web session with a person's API key (agents cannot). The token is shown once; only its hash is stored. It expires after 8 hours idle or 7 days.", "tags": [ "sessions" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Opened", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/Session" }, "token": { "type": [ "string", "null" ], "description": "Bearer token for this session (ebs_...). null on an idempotent replay." } }, "required": [ "session", "token" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" }, "get": { "operationId": "listSessions", "summary": "Your active web sessions", "tags": [ "sessions" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/Session" } } }, "required": [ "sessions" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/sessions/{id}/revoke": { "post": { "operationId": "revokeSession", "summary": "Sign a session out (your own; admins: anyone's in the company)", "tags": [ "sessions" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "reason": "signed out" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/Session" } }, "required": [ "session" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/audit/actors": { "get": { "operationId": "listAuditActors", "summary": "Everyone who has acted on these books: people, agents (with each model they declared) and the system, with event counts", "tags": [ "audit" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Actors", "content": { "application/json": { "schema": { "type": "object", "properties": { "actors": { "type": "array", "items": { "$ref": "#/components/schemas/AuditActor" } } }, "required": [ "actors" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbwc/connections": { "post": { "operationId": "createQbwcConnection", "summary": "Create a Web Connector migration connection (people only): read-only, for a migration window. Returns the password and a single-use .qwc download token ONCE; only their hashes are stored.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Export date: reports, aging and the last tie-out period (usually the cutover date)." }, "include_tax_ids": { "type": "boolean", "description": "Keep SSNs/tax IDs (needed for 1099s). Card numbers are always redacted." } }, "required": [ "as_of" ], "additionalProperties": false }, "example": { "as_of": "2026-09-30" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbwcConnection" }, "password": { "type": [ "string", "null" ], "description": "Type it into Web Connector. Shown once; null on an idempotent replay." }, "download_token": { "type": [ "string", "null" ], "description": "Single-use, 24 h: POST it to .../qwc to get the .qwc file. null on a replay." } }, "required": [ "connection", "password", "download_token" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listQbwcConnections", "summary": "Web Connector migration connections, newest first", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/QbwcConnection" } } }, "required": [ "connections" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbwc/connections/{id}": { "get": { "operationId": "getQbwcConnection", "summary": "A connection with live progress per extraction step, the bundle and its imports", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Connection", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbwcConnection" }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/QbwcBundle" }, { "type": "null" } ] }, "migrations": { "type": "array", "items": { "$ref": "#/components/schemas/Migration" } } }, "required": [ "connection", "bundle", "migrations" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbwc/connections/{id}/qwc": { "post": { "operationId": "downloadQbwcFile", "summary": "Redeem the single-use download token for the .qwc file to add to Web Connector (people only; audited)", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "download_token": { "type": "string", "minLength": 20, "maxLength": 100 } }, "required": [ "download_token" ], "additionalProperties": false }, "example": { "download_token": "token-shown-once-at-creation" } } } }, "responses": { "200": { "description": "The .qwc file", "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string" }, "qwc": { "type": [ "string", "null" ], "description": "XML; null on an idempotent replay" } }, "required": [ "filename", "qwc" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbwc/connections/{id}/tieout": { "get": { "operationId": "getQbwcTieout", "summary": "The extraction's tie-out report (JSON and the readable Markdown) once the bundle exists", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Tie-out", "content": { "application/json": { "schema": { "type": "object", "properties": { "tieout": { "type": "object" }, "markdown": { "type": "string" } }, "required": [ "tieout", "markdown" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbwc/connections/{id}/revoke": { "post": { "operationId": "revokeQbwcConnection", "summary": "Revoke a connection: Web Connector is refused from now on (nvu), sessions end, staged raw data is wiped. Final.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "extraction finished" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbwcConnection" } }, "required": [ "connection" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbwc/connections/{id}/unlock": { "post": { "operationId": "unlockQbwcConnection", "summary": "Unlock a connection locked after repeated wrong passwords", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Unlocked", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QbwcConnection" } }, "required": [ "connection" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbwc/connections/{id}/import": { "post": { "operationId": "importQbwcBundle", "summary": "Import the connection's bundle into these (empty) books (people only). Refused unless the extraction tie-out passed; the ledger then runs its own tie-out: on any difference nothing is kept and the attempt is recorded as failed.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Recorded: imported (result PASS) or failed (result FAIL, with the report)", "content": { "application/json": { "schema": { "type": "object", "properties": { "migration": { "$ref": "#/components/schemas/Migration" } }, "required": [ "migration" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations": { "get": { "operationId": "listMigrations", "summary": "Migration imports into this company with their tie-out results", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Migrations", "content": { "application/json": { "schema": { "type": "object", "properties": { "migrations": { "type": "array", "items": { "$ref": "#/components/schemas/Migration" } } }, "required": [ "migrations" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/{id}/cutover": { "post": { "operationId": "cutoverMigration", "summary": "Cut over to Evenbead (people only): needs an imported migration whose tie-out passed; revokes its Web Connector or QuickBooks Online connection. Final.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Cut over", "content": { "application/json": { "schema": { "type": "object", "properties": { "migration": { "$ref": "#/components/schemas/Migration" }, "connection": { "anyOf": [ { "$ref": "#/components/schemas/QbwcConnection" }, { "type": "null" } ] }, "qbo_connection": { "anyOf": [ { "$ref": "#/components/schemas/QboConnection" }, { "type": "null" } ] } }, "required": [ "migration", "connection" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm-access": { "post": { "operationId": "grantFirmAccess", "summary": "Grant an accounting firm access to this company (the company's own people only): scopes are the ceiling for every firm member and agent here; billing is recorded only. Audited here and in the firm's log.", "tags": [ "firm-access" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "firm_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "billing": { "type": "string", "enum": [ "firm", "client" ], "description": "Who pays for the company file (ADR-0009): firm-billed wholesale or client-billed. Recorded only." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "firm_id", "scopes", "billing" ], "additionalProperties": false }, "example": { "firm_id": "00000000-0000-4000-8000-000000000000", "scopes": [ "read", "propose", "approve" ], "billing": "client", "reason": "Okafor & Partners keeps our books" } } } }, "responses": { "201": { "description": "Granted", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "$ref": "#/components/schemas/FirmGrant" } }, "required": [ "grant" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listFirmAccess", "summary": "Firms with access to this company (and revoked grants)", "tags": [ "firm-access" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Grants", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "$ref": "#/components/schemas/FirmGrant" } } }, "required": [ "grants" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm-access/{id}/revoke": { "post": { "operationId": "revokeFirmAccess", "summary": "Revoke a firm's access (effective on its next request; its agents are unassigned here). A firm may also give up its own access. Final.", "tags": [ "firm-access" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "changed accountants" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "$ref": "#/components/schemas/FirmGrant" } }, "required": [ "grant" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm-access/{id}/update": { "post": { "operationId": "updateFirmAccess", "summary": "Change the billing flag of a live grant (record only; scopes are fixed: revoke and grant again)", "tags": [ "firm-access" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "billing": { "type": "string", "enum": [ "firm", "client" ], "description": "Who pays for the company file (ADR-0009): firm-billed wholesale or client-billed. Recorded only." } }, "required": [ "billing" ], "additionalProperties": false }, "example": { "billing": "firm" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "grant": { "$ref": "#/components/schemas/FirmGrant" } }, "required": [ "grant" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firms": { "post": { "operationId": "createFirm", "summary": "Create an accounting firm with its first admin member and that member's key (returned once). Operator bootstrap token required.", "tags": [ "firm" ], "security": [ { "bootstrap": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "admin_name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name", "admin_name" ], "additionalProperties": false }, "example": { "name": "Okafor & Partners CPAs", "admin_name": "Dana Okafor" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "firm": { "$ref": "#/components/schemas/Firm" }, "member": { "$ref": "#/components/schemas/FirmMember" }, "api_key": { "$ref": "#/components/schemas/IssuedFirmKey" } }, "required": [ "firm", "member", "api_key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/firm": { "get": { "operationId": "getFirm", "summary": "The caller's firm and who the caller is (firm key or firm session)", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Firm", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FirmMe" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/members": { "post": { "operationId": "createFirmMember", "summary": "Add a firm member (firm admin). They appear in every client that granted the firm access. No seat fees.", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "role": { "type": "string", "enum": [ "admin", "cpa", "bookkeeper" ], "description": "admin and cpa: all scopes in clients (admin also manages the firm); bookkeeper: read and propose." } }, "required": [ "name", "role" ], "additionalProperties": false }, "example": { "name": "Lee Park", "role": "bookkeeper" } } } }, "responses": { "201": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/FirmMember" } }, "required": [ "member" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listFirmMembers", "summary": "Firm members", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_removed", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Members", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/FirmMember" } } }, "required": [ "members" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/members/{id}/remove": { "post": { "operationId": "removeFirmMember", "summary": "Remove a member (firm admin): their keys and sessions end at once. Final.", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "left the firm" } } } }, "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "member": { "$ref": "#/components/schemas/FirmMember" } }, "required": [ "member" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/keys": { "post": { "operationId": "createFirmKey", "summary": "Mint a firm key for a member or a firm agent (firm admin). The secret is returned once; only its hash is stored. Use it with X-Evenbead-Company on any company operation.", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal_type": { "type": "string", "enum": [ "member", "agent" ] }, "member_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "firm_agent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Lifetime in days. Default: 365 for a member's key, 30 for a firm agent's (at most 90)." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the firm default)." } }, "required": [ "principal_type", "scopes" ], "additionalProperties": false }, "example": { "principal_type": "agent", "firm_agent_id": "00000000-0000-4000-8000-000000000000", "scopes": [ "read", "propose" ], "expires_in_days": 30 } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/IssuedFirmKey" }, "key": { "$ref": "#/components/schemas/FirmKey" } }, "required": [ "api_key", "key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listFirmKeys", "summary": "Firm keys (prefixes only, never secrets)", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/FirmKey" } } }, "required": [ "keys" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/keys/{id}/rotate": { "post": { "operationId": "rotateFirmKey", "summary": "Rotate a live firm key (firm admin, or the key's own holder): a successor with the same principal and scopes and a fresh lifetime; the old key keeps working for the overlap window (default 24 h, at most 7 days, 0 = at once). The new secret is returned once.", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overlap_seconds": { "type": "integer", "minimum": 0, "maximum": 604800 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "description": "Lifetime in days. Default: 365 for a member's key, 30 for a firm agent's (at most 90)." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the firm default)." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "overlap_seconds": 3600, "reason": "monthly rotation" } } } }, "responses": { "201": { "description": "Rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/IssuedFirmKey" }, "key": { "$ref": "#/components/schemas/FirmKey" }, "previous": { "$ref": "#/components/schemas/FirmKey" } }, "required": [ "api_key", "key", "previous" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/keys/{id}/revoke": { "post": { "operationId": "revokeFirmKey", "summary": "Revoke a firm key (and its sessions), effective on the next request", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "rotated" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FirmKey" } }, "required": [ "key" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/agents": { "post": { "operationId": "createFirmAgent", "summary": "Register a firm agent (firm admin). It acts only in clients it is assigned to, with each client's own threshold.", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "name", "scopes" ], "additionalProperties": false }, "example": { "name": "categorizer", "scopes": [ "read", "propose" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/FirmAgent" } }, "required": [ "agent" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listFirmAgents", "summary": "Firm agents with their client assignments and per-client thresholds", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "agents": { "type": "array", "items": { "$ref": "#/components/schemas/FirmAgent" } } }, "required": [ "agents" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/agents/{id}/assign": { "post": { "operationId": "assignFirmAgent", "summary": "Assign a firm agent to a client that granted the firm access, with that client's posting threshold (upsert; a threshold change is audited in the client's log)", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "posting_threshold_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 } }, "required": [ "company_id", "posting_threshold_cents" ], "additionalProperties": false }, "example": { "company_id": "00000000-0000-4000-8000-000000000000", "posting_threshold_cents": 50000 } } } }, "responses": { "200": { "description": "Assigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/FirmAgent" } }, "required": [ "agent" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/agents/{id}/unassign": { "post": { "operationId": "unassignFirmAgent", "summary": "Stop a firm agent from acting in one client", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "company_id", "reason" ], "additionalProperties": false }, "example": { "company_id": "00000000-0000-4000-8000-000000000000", "reason": "client asked" } } } }, "responses": { "200": { "description": "Unassigned", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/FirmAgent" } }, "required": [ "agent" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/agents/{id}/revoke": { "post": { "operationId": "revokeFirmAgent", "summary": "Revoke a firm agent everywhere (and its keys). Final.", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "decommissioned" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "agent": { "$ref": "#/components/schemas/FirmAgent" } }, "required": [ "agent" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/clients": { "get": { "operationId": "listFirmClients", "summary": "The console: every client that granted the firm access, with status at a glance (bank, proposal queue, period locks, overdue AR, last activity, migration)", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Clients", "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientStatus" } } }, "required": [ "as_of", "clients" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" }, "post": { "operationId": "createFirmClient", "summary": "Create a new client company (firm admin): owner user, firm-billed grant to this firm with all scopes, and a single-use owner invitation (returned once, 14 days) for the firm to hand to the owner. The firm never receives a company key; the owner claims theirs (ADR-0023).", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "owner_name": { "type": "string", "minLength": 1, "maxLength": 200 }, "starter_chart": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts (default general; empty for a migration)." }, "periods": { "type": "boolean", "description": "Create this fiscal year's and the next one's monthly periods (default true; false for a custom calendar)" } }, "required": [ "name", "owner_name" ], "additionalProperties": false }, "example": { "name": "Maple Street Cafe LLC", "owner_name": "Ana Maple", "starter_chart": "general" } } } }, "responses": { "201": { "description": "Created, with the starter chart applied and this fiscal year's and the next one's monthly periods", "content": { "application/json": { "schema": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" }, "owner": { "$ref": "#/components/schemas/User" }, "owner_invite": { "$ref": "#/components/schemas/OwnerInviteIssued" }, "grant": { "$ref": "#/components/schemas/FirmGrant" }, "setup": { "$ref": "#/components/schemas/CompanySetup" } }, "required": [ "company", "owner", "owner_invite", "grant" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/clients/{id}/owner-invite": { "post": { "operationId": "createOwnerInvite", "summary": "Issue a new owner invitation for a client the firm created (firm admin), replacing an unclaimed one. Refused once the owner has claimed the company or after the client revoked the firm's access.", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_invite": { "$ref": "#/components/schemas/OwnerInviteIssued" } }, "required": [ "owner_invite" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/clients/lock-period": { "post": { "operationId": "lockClientPeriods", "summary": "Bulk: lock the period containing a date in each selected client (people only). Each company is locked separately, as you, and audited in its own log; one failure never blocks the others. dry_run previews.", "tags": [ "firm" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "company_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "minItems": 1, "maxItems": 100 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "status": { "type": "string", "enum": [ "soft_locked", "hard_locked" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "dry_run": { "type": "boolean" } }, "required": [ "company_ids", "date", "status", "reason" ], "additionalProperties": false }, "example": { "company_ids": [ "00000000-0000-4000-8000-000000000000" ], "date": "2026-09-30", "status": "soft_locked", "reason": "September closed" } } } }, "responses": { "200": { "description": "Per-company results", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkLockResult" } } }, "required": [ "dry_run", "results" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/firm/kill-switch": { "post": { "operationId": "setFirmKillSwitch", "summary": "Suspend or resume every firm agent's writes in every client (firm admin)", "tags": [ "firm" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "suspended": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "suspended", "reason" ], "additionalProperties": false }, "example": { "suspended": true, "reason": "agent misbehaving" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "firm": { "$ref": "#/components/schemas/Firm" } }, "required": [ "firm" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/sessions": { "post": { "operationId": "createFirmSession", "summary": "Open a firm web session with a member's firm key (ebf_ token shown once, stored hashed; 8 hours idle, 7 days at most)", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Opened", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/FirmSession" }, "token": { "type": [ "string", "null" ] } }, "required": [ "session", "token" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" }, "get": { "operationId": "listFirmSessions", "summary": "Your active firm sessions", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/FirmSession" } } }, "required": [ "sessions" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/sessions/{id}/revoke": { "post": { "operationId": "revokeFirmSession", "summary": "Sign a firm session out (your own; firm admins: anyone's)", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "reason": "signed out" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "$ref": "#/components/schemas/FirmSession" } }, "required": [ "session" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/audit/verify": { "get": { "operationId": "verifyFirmAudit", "summary": "Verify the firm's own audit hash chain", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Verdict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditVerdict" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/audit/events": { "get": { "operationId": "listFirmAuditEvents", "summary": "The firm's audit events, newest first", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "before_seq", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Events", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } }, "required": [ "events" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/sales-receipts": { "post": { "operationId": "createSalesReceipt", "summary": "Record a sale paid on the spot (Dr the deposit account, Cr income per line, plus sales tax). Never open, not in AR. Same governance as invoices; dry_run previews.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The customer" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (SR-0001) when omitted" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "deposit_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Bank, cash or undeposited-funds account the money went to" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100 }, "memo": { "type": "string", "maxLength": 500 }, "tax_rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 198 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contact_id", "doc_date", "deposit_account", "lines" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "doc_date": "2026-09-15", "deposit_account": "1300", "lines": [ { "description": "Counter sale: two dozen croissants", "account": "4000", "quantity": 2, "unit_price_cents": 3600 } ] } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/payments/{id}/apply": { "post": { "operationId": "applyPayment", "summary": "Apply a payment's unapplied amount (credit on account, deposit, prepayment) to open invoices or bills of the same customer or vendor", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "properties": { "document_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "document_id", "amount_cents" ], "additionalProperties": false } }, "applied_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "dry_run": { "type": "boolean" } }, "required": [ "applications" ], "additionalProperties": false }, "example": { "applications": [ { "document_id": "00000000-0000-4000-8000-000000000000", "amount_cents": 2500 } ] } } } }, "responses": { "200": { "description": "Applied (or the dry-run preview)", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "payment": { "$ref": "#/components/schemas/Payment" }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } }, "required": [ "payment" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/refunds": { "post": { "operationId": "createRefund", "summary": "Refund a customer from the unapplied part of a payment (deposit, overpayment) or a credit memo: a refund document (Dr AR, Cr bank) paid at once by its source. Same governance as invoices; dry_run previews.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Refund from this payment received (give this or credit_id)" }, "credit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Refund from this credit memo" }, "refund_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Bank, cash or card account the money leaves" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Default: everything left on the source" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (RF-0001) when omitted" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Check no." }, "memo": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "refund_date", "account" ], "additionalProperties": false }, "example": { "payment_id": "00000000-0000-4000-8000-000000000000", "refund_date": "2026-09-25", "account": "1000", "amount_cents": 5000, "reference": "CHK 1077" } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/documents/{id}/pdf": { "get": { "operationId": "renderDocumentPdf", "summary": "Render an invoice, credit memo or sales receipt as a PDF (server-side, Plus Jakarta Sans embedded; nothing is sent anywhere)", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pdf", "base64" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "The PDF (or with format=base64, JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfFile" } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "The rendered PDF (default). format=base64 returns the JSON form instead." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/estimates": { "post": { "operationId": "createEstimate", "summary": "Create an estimate for a customer (never posts; convert it into an invoice later). dry_run previews number and totals.", "tags": [ "estimates" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (EST-0001) when omitted" }, "estimate_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "expiry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "reference": { "type": "string", "minLength": 1, "maxLength": 100 }, "memo": { "type": "string", "maxLength": 500 }, "tax_rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 198 }, "dry_run": { "type": "boolean" } }, "required": [ "contact_id", "estimate_date", "lines" ], "additionalProperties": false }, "example": { "contact_id": "00000000-0000-4000-8000-000000000000", "estimate_date": "2026-09-01", "expiry_date": "2026-09-30", "lines": [ { "description": "Wedding cake, 3 tier", "account": "4100", "quantity": 1, "unit_price_cents": 45000 } ] } } } }, "responses": { "200": { "description": "Dry run: the estimate it would create", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "const": true }, "valid": { "type": "boolean" }, "estimate": { "$ref": "#/components/schemas/Estimate" }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } } }, "required": [ "dry_run", "valid" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "estimate": { "$ref": "#/components/schemas/Estimate" } }, "required": [ "estimate" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" }, "get": { "operationId": "listEstimates", "summary": "Estimates, newest first", "tags": [ "estimates" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "accepted", "declined", "converted", "void" ] } }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Estimates", "content": { "application/json": { "schema": { "type": "object", "properties": { "estimates": { "type": "array", "items": { "$ref": "#/components/schemas/Estimate" } } }, "required": [ "estimates" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/estimates/{id}": { "get": { "operationId": "getEstimate", "summary": "One estimate with its lines", "tags": [ "estimates" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "estimate": { "$ref": "#/components/schemas/Estimate" } }, "required": [ "estimate" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/estimates/{id}/status": { "post": { "operationId": "setEstimateStatus", "summary": "Mark an estimate accepted, declined, open again, or void it (with a reason). Converted and void are final.", "tags": [ "estimates" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "accepted", "declined", "void" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "status" ], "additionalProperties": false }, "example": { "status": "accepted" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "estimate": { "$ref": "#/components/schemas/Estimate" } }, "required": [ "estimate" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/estimates/{id}/convert": { "post": { "operationId": "convertEstimate", "summary": "Convert an open or accepted estimate into an invoice (its lines, prices and tax rate), through the same governance as creating an invoice; the estimate is marked converted with it.", "tags": [ "estimates" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Invoice date (default: the server's today)" }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$" }, "memo": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "doc_date": "2026-09-20" } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Invoice posted; estimate converted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/estimates/{id}/pdf": { "get": { "operationId": "renderEstimatePdf", "summary": "Render an estimate as a PDF (server-side; nothing is sent anywhere)", "tags": [ "estimates" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pdf", "base64" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "The PDF (or with format=base64, JSON)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfFile" } }, "application/pdf": { "schema": { "type": "string", "format": "binary", "description": "The rendered PDF (default). format=base64 returns the JSON form instead." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/tax-agencies": { "post": { "operationId": "createTaxAgency", "summary": "Add a sales-tax agency (optionally linked to a vendor for paying it)", "tags": [ "sales-tax" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^\\S(.*\\S)?$" }, "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Tennessee Department of Revenue" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_agency": { "$ref": "#/components/schemas/TaxAgency" } }, "required": [ "tax_agency" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listTaxAgencies", "summary": "Sales-tax agencies", "tags": [ "sales-tax" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Agencies", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_agencies": { "type": "array", "items": { "$ref": "#/components/schemas/TaxAgency" } } }, "required": [ "tax_agencies" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/tax-rates": { "post": { "operationId": "createTaxRate", "summary": "Add a sales-tax rate (percent with up to 4 decimals) collected for an agency into a liability account. Rates are never edited: add a new one and deactivate the old.", "tags": [ "sales-tax" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\S(.*\\S)?$" }, "agency_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "rate_percent": { "type": "string", "pattern": "^\\d{1,3}(\\.\\d{1,4})?$", "description": "e.g. \"9.75\"" }, "payable_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Sales tax payable (a liability account)" } }, "required": [ "name", "agency_id", "rate_percent", "payable_account" ], "additionalProperties": false }, "example": { "name": "Davidson County", "agency_id": "00000000-0000-4000-8000-000000000000", "rate_percent": "9.75", "payable_account": "2200" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate": { "$ref": "#/components/schemas/TaxRate" } }, "required": [ "tax_rate" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listTaxRates", "summary": "Sales-tax rates", "tags": [ "sales-tax" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "include_inactive", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Rates", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rates": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRate" } } }, "required": [ "tax_rates" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/tax-rates/{id}/status": { "post": { "operationId": "setTaxRateStatus", "summary": "Deactivate (or reactivate) a tax rate; documents keep the rate they used", "tags": [ "sales-tax" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "active", "reason" ], "additionalProperties": false }, "example": { "active": false, "reason": "Rate rose to 9.85% on 2027-01-01" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate": { "$ref": "#/components/schemas/TaxRate" } }, "required": [ "tax_rate" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/reports/sales-tax": { "get": { "operationId": "getSalesTaxReport", "summary": "Sales-tax liability for a period: taxable and non-taxable sales and tax by rate, jurisdiction, agency and month or quarter (accrual, by document date; voids reverse on their date), with what the payable accounts hold and the ledger tie-out. Filing is out of scope.", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "group_by", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "month", "quarter" ] } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Sales-tax liability", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesTaxReport" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/recurring-templates": { "post": { "operationId": "createRecurringTemplate", "summary": "Schedule a recurring invoice or bill. Nothing posts until the schedule is run; each occurrence then goes through the same governance as any invoice or bill, once per date.", "tags": [ "recurring" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\S(.*\\S)?$" }, "kind": { "type": "string", "enum": [ "invoice", "bill" ] }, "frequency": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 52, "description": "Every N weeks/months/quarters/years (default 1)" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "The first occurrence; months clamp to the month end" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "request": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "terms_days": { "type": "integer", "minimum": 0, "maximum": 365 }, "reference": { "type": "string", "minLength": 1, "maxLength": 100 }, "memo": { "type": "string", "maxLength": 500 }, "control_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "tax_rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 198 } }, "required": [ "contact_id", "lines" ], "additionalProperties": false } }, "required": [ "name", "kind", "frequency", "start_date", "request" ], "additionalProperties": false }, "example": { "name": "Maple Street weekly bread", "kind": "invoice", "frequency": "monthly", "start_date": "2026-09-01", "request": { "contact_id": "00000000-0000-4000-8000-000000000000", "lines": [ { "description": "Bread standing order", "account": "4000", "unit_price_cents": 48000 } ] } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/RecurringTemplate" } }, "required": [ "template" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" }, "get": { "operationId": "listRecurringTemplates", "summary": "Recurring templates with their next occurrence", "tags": [ "recurring" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "active", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Templates", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringTemplate" } } }, "required": [ "templates" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/recurring-templates/{id}": { "get": { "operationId": "getRecurringTemplate", "summary": "A recurring template with every occurrence generated so far", "tags": [ "recurring" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Template", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/RecurringTemplate" }, "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringRun" } } }, "required": [ "template", "runs" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/recurring-templates/{id}/update": { "post": { "operationId": "updateRecurringTemplate", "summary": "Pause or resume a template, or change its end date (anything else: a new template)", "tags": [ "recurring" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" }, "end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "active": false, "reason": "Customer on holiday in December" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/RecurringTemplate" } }, "required": [ "template" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/recurring-templates/{id}/run": { "post": { "operationId": "runRecurringTemplate", "summary": "Generate every occurrence due through a date (default: the server's today) that has not been generated yet, through the governed path (agents: within policy it posts, else a proposal). Idempotent per occurrence. dry_run previews.", "tags": [ "recurring" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "dry_run": { "type": "boolean" } }, "additionalProperties": false }, "example": { "through": "2026-10-31" } } } }, "responses": { "200": { "description": "Occurrences generated, queued or refused (or previewed)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringRunResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/recurring/run": { "post": { "operationId": "runDueRecurring", "summary": "Run every active recurring template through a date (default: the server's today): what a scheduler agent calls daily", "tags": [ "recurring" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "dry_run": { "type": "boolean" } }, "additionalProperties": false }, "example": { "through": "2026-10-31" } } } }, "responses": { "200": { "description": "Per template", "content": { "application/json": { "schema": { "type": "object", "properties": { "through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "dry_run": { "type": "boolean" }, "templates": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringRunResult" } } }, "required": [ "through", "dry_run", "templates" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/close/checklist": { "get": { "operationId": "getCloseChecklist", "summary": "The month-end close checklist of the period containing a date: bank accounts reconciled through the period end, no pending proposal dated in it, no unapplied payment older than N days, AR/AP aging tied to the control accounts, sales-tax liability reviewed (and unchanged since), then the lock. Computed live from the books.", "tags": [ "close" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "unapplied_days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 3660 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Checklist", "content": { "application/json": { "schema": { "type": "object", "properties": { "checklist": { "$ref": "#/components/schemas/CloseChecklist" } }, "required": [ "checklist" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/close/sales-tax-review": { "post": { "operationId": "reviewSalesTax", "summary": "Sign off the period's sales-tax liability as reviewed (people with approve; agents are refused). The liability by agency is kept with the sign-off; if it changes later the checklist asks for a new review. Audited.", "tags": [ "close" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "date" ], "additionalProperties": false }, "example": { "date": "2026-09-30", "note": "Matches the September return" } } } }, "responses": { "200": { "description": "Reviewed", "content": { "application/json": { "schema": { "type": "object", "properties": { "signoff": { "$ref": "#/components/schemas/CloseSignoff" }, "checklist": { "$ref": "#/components/schemas/CloseChecklist" } }, "required": [ "signoff", "checklist" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/close/lock": { "post": { "operationId": "closePeriod", "summary": "Close the period: lock it (soft or hard) only if every checklist item passes, else 422 close_incomplete listing the failing items. People only. The lock and the checklist as it stood are recorded and audited. dry_run reports what would happen.", "tags": [ "close" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "status": { "type": "string", "enum": [ "soft_locked", "hard_locked" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "unapplied_days": { "type": "integer", "minimum": 0, "maximum": 3660 }, "dry_run": { "type": "boolean" } }, "required": [ "date", "status", "reason" ], "additionalProperties": false }, "example": { "date": "2026-09-30", "status": "soft_locked", "reason": "September closed" } } } }, "responses": { "200": { "description": "Closed (or previewed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "period": { "$ref": "#/components/schemas/Period" }, "checklist": { "$ref": "#/components/schemas/CloseChecklist" }, "signoff": { "anyOf": [ { "$ref": "#/components/schemas/CloseSignoff" }, { "type": "null" } ] } }, "required": [ "dry_run", "period", "checklist" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/firm/proposals": { "get": { "operationId": "listClientProposals", "summary": "The approval queue across every client that granted the firm access: pending proposals, oldest first, filtered by client, agent (the agent in the company or the firm agent behind it; or by name), amount and age.", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "company_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "agent_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "agent_name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "min_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents." } }, { "name": "max_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents." } }, { "name": "older_than_days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 3660 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Pending proposals", "content": { "application/json": { "schema": { "type": "object", "properties": { "proposals": { "type": "array", "items": { "$ref": "#/components/schemas/ClientProposal" } }, "truncated": { "type": "boolean", "description": "More match than the limit" } }, "required": [ "proposals", "truncated" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/firm/proposals/decide": { "post": { "operationId": "decideClientProposals", "summary": "Batch approve or reject proposals across clients (firm members only; reject needs a reason). Each decision runs separately in its company as you, through the same rules as a single approval, and is audited in that company's log; one failure never blocks the others (per-item results). dry_run previews.", "tags": [ "firm" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "items": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "company_id", "proposal_id" ], "additionalProperties": false } }, "dry_run": { "type": "boolean" } }, "required": [ "decision", "items" ], "additionalProperties": false }, "example": { "decision": "approve", "reason": "Reviewed against the bank feed", "items": [ { "company_id": "00000000-0000-4000-8000-000000000000", "proposal_id": "00000000-0000-4000-8000-000000000001" } ] } } } }, "responses": { "200": { "description": "Per-item results", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "batch_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ProposalDecisionResult" } }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } }, "required": [ "dry_run", "batch_id", "decision", "results", "succeeded", "failed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/firm/close": { "get": { "operationId": "listClientCloseStatus", "summary": "The close checklist of the period containing a date in every client that granted the firm access", "tags": [ "firm" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "date", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "unapplied_days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 3660 } }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Per client", "content": { "application/json": { "schema": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientCloseStatus" } } }, "required": [ "date", "clients" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/tax-rates/combined": { "post": { "operationId": "createCombinedTaxRate", "summary": "Combine 2-10 single-agency rates into one rate for documents (e.g. state + county + city). Its rate is their sum; a document taxed at it carries one tax line per jurisdiction, each rounded on its own and posted to that agency's payable account. Never edited: create a new combined rate and deactivate the old (deactivating a component deactivates it too).", "tags": [ "sales-tax" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\S(.*\\S)?$" }, "component_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "minItems": 2, "maxItems": 10, "description": "Single-agency tax rates, in the order shown on documents" } }, "required": [ "name", "component_ids" ], "additionalProperties": false }, "example": { "name": "Nashville combined", "component_ids": [ "00000000-0000-4000-8000-000000000001", "00000000-0000-4000-8000-000000000002", "00000000-0000-4000-8000-000000000003" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "tax_rate": { "$ref": "#/components/schemas/TaxRate" } }, "required": [ "tax_rate" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/vendor-refunds": { "post": { "operationId": "createVendorRefund", "summary": "Record money a vendor paid back, from the unapplied part of a payment made (a prepayment, an overpaid bill) or a vendor credit: a vendor refund document (Cr AP, Dr the bank account) paid at once by its source. Same governance as bills; dry_run previews.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Refund of this payment made (give this or credit_id)" }, "credit_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Refund of this vendor credit" }, "refund_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Bank, cash or card account the money arrives in" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Default: everything left on the source" }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (VRF-0001) when omitted" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Deposit or check no." }, "memo": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "refund_date", "account" ], "additionalProperties": false }, "example": { "payment_id": "00000000-0000-4000-8000-000000000000", "refund_date": "2026-09-25", "account": "1000", "amount_cents": 15000, "reference": "DEP 4411" } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/migrations/qbo/connections": { "post": { "operationId": "createQboConnection", "summary": "Start a QuickBooks Online migration (people only): returns Intuit's consent URL once, with a single-use state valid for 15 minutes. Read-only access (accounting scope); nothing is written to QuickBooks.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Export date: transactions through this date, reports and aging as of it." }, "include_tax_ids": { "type": "boolean", "description": "Keep vendor tax IDs (QBO returns them masked)." } }, "required": [ "as_of" ], "additionalProperties": false }, "example": { "as_of": "2026-09-30" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QboConnection" }, "authorize_url": { "type": [ "string", "null" ], "description": "Open it as the person with the QuickBooks Online login. Shown once; null on an idempotent replay." } }, "required": [ "connection", "authorize_url" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" }, "get": { "operationId": "listQboConnections", "summary": "QuickBooks Online migration connections, newest first", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Connections", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "array", "items": { "$ref": "#/components/schemas/QboConnection" } } }, "required": [ "connections" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbo/connections/{id}": { "get": { "operationId": "getQboConnection", "summary": "A QuickBooks Online connection with its bundle and import attempts", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Connection", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QboConnection" }, "bundle": { "anyOf": [ { "$ref": "#/components/schemas/QboBundle" }, { "type": "null" } ] }, "migrations": { "type": "array", "items": { "$ref": "#/components/schemas/Migration" } } }, "required": [ "connection", "bundle", "migrations" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbo/connections/{id}/authorize": { "post": { "operationId": "authorizeQboConnection", "summary": "Finish Intuit's consent (people only): the code, state and realmId Intuit sent to the redirect URI. The code is exchanged once; tokens are sealed at rest and rotated on refresh; the QuickBooks company is recorded once.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 2000 }, "state": { "type": "string", "minLength": 20, "maxLength": 200 }, "realm_id": { "type": "string", "pattern": "^[0-9]{1,32}$" } }, "required": [ "code", "state", "realm_id" ], "additionalProperties": false }, "example": { "code": "code-from-intuit", "state": "state-from-the-authorize-url", "realm_id": "9130000000000001" } } } }, "responses": { "200": { "description": "Authorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QboConnection" } }, "required": [ "connection" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "QuickBooks Online or Intuit's OAuth service refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbo/connections/{id}/estimate": { "post": { "operationId": "estimateQboConnection", "summary": "Pre-flight: count the company's records (metered reads themselves) and estimate the extraction's calls against this month's read budget", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Estimate", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QboConnection" }, "estimate": { "$ref": "#/components/schemas/QboCallEstimate" }, "preflight_calls": { "type": "integer" }, "budget": { "type": "object", "properties": { "month": { "type": "string" }, "used": { "type": "integer" }, "budget": { "type": "integer" }, "remaining": { "type": "integer" }, "fits": { "type": "boolean" } }, "required": [ "month", "used", "budget", "remaining", "fits" ] } }, "required": [ "connection", "estimate", "preflight_calls", "budget" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "QuickBooks Online or Intuit's OAuth service refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbo/connections/{id}/extract": { "post": { "operationId": "extractQboConnection", "summary": "Run the extraction: every list and posting transaction through the export date (pages of 1,000), Trial Balance per month-end, General Ledger per month, AR/AP aging; the evenbead-export bundle (sealed at rest), the Desktop tie-out and the disclosure report. Refused (budget_exceeded) when the last estimate does not fit this month's remaining reads.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Extracted (status extracted) or tie-out failed (status failed)", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QboConnection" }, "bundle": { "$ref": "#/components/schemas/QboBundle" }, "tieout": { "type": "object" } }, "required": [ "connection", "bundle", "tieout" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "QuickBooks Online or Intuit's OAuth service refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbo/connections/{id}/tieout": { "get": { "operationId": "getQboTieout", "summary": "The extraction's tie-out (JSON and Markdown): trial balance per month-end, coverage, per-document checks, AR/AP aging", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Tie-out", "content": { "application/json": { "schema": { "type": "object", "properties": { "tieout": { "type": "object" }, "markdown": { "type": "string" } }, "required": [ "tieout", "markdown" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbo/connections/{id}/disclosure": { "get": { "operationId": "getQboDisclosure", "summary": "What QuickBooks Online could not export for this company (audit log, reconciliation state, bank rules, attachments, ...) and how each is handled", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Disclosure", "content": { "application/json": { "schema": { "type": "object", "properties": { "disclosure": { "type": "object", "properties": { "format": { "const": "evenbead-qbo-disclosure" }, "items": { "type": "array", "items": { "type": "object", "properties": { "object": { "type": "string" }, "status": { "type": "string" }, "found": { "type": "string" }, "handling": { "type": "string" } }, "required": [ "object", "status", "found", "handling" ] } } }, "required": [ "format", "items" ] }, "markdown": { "type": "string" } }, "required": [ "disclosure", "markdown" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/migrations/qbo/connections/{id}/import": { "post": { "operationId": "importQboBundle", "summary": "Import the extraction's bundle into these (empty) books (people only), with the same importer and ledger tie-out as Desktop; then cut over with POST /v1/migrations/{id}/cutover", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Recorded: imported (PASS) or failed (FAIL, with the report)", "content": { "application/json": { "schema": { "type": "object", "properties": { "migration": { "$ref": "#/components/schemas/Migration" } }, "required": [ "migration" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbo/connections/{id}/revoke": { "post": { "operationId": "revokeQboConnection", "summary": "Revoke a connection: tokens revoked at Intuit (best effort) and wiped here. Final.", "tags": [ "migrations" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "migration finished" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection": { "$ref": "#/components/schemas/QboConnection" } }, "required": [ "connection" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/migrations/qbo/usage": { "get": { "operationId": "getQboUsage", "summary": "This month's metered QuickBooks Online reads for the deployment against its budget (reads of our own data are never metered; Intuit meters ours)", "tags": [ "migrations" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QboUsage" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/items/{id}": { "get": { "operationId": "getItem", "summary": "One product or service", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Item", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Item" } }, "required": [ "item" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/items/{id}/update": { "post": { "operationId": "updateItem", "summary": "Edit a product or service (name, kind, description, sales price, income account, purchase cost and account, taxable) or deactivate/reactivate it. Documents keep what they posted. Audited; dry_run previews.", "tags": [ "sales-purchases" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^\\S(.*\\S)?$" }, "kind": { "type": "string", "enum": [ "service", "non_inventory" ] }, "description": { "type": "string", "maxLength": 500 }, "sales_price_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "purchase_cost_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "income_account": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "An income account (selling); null removes it" }, "expense_account": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "An expense or inventory-asset account (buying); null removes it" }, "taxable": { "type": "boolean" }, "active": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "additionalProperties": false }, "example": { "sales_price_cents": 17500, "taxable": true } } } }, "responses": { "200": { "description": "Updated (or, with dry_run, what it would be)", "content": { "application/json": { "schema": { "type": "object", "properties": { "item": { "$ref": "#/components/schemas/Item" }, "dry_run": { "type": "boolean" } }, "required": [ "item" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/expenses": { "post": { "operationId": "createExpense", "summary": "Record money already spent, without a bill: Dr the expense lines, Cr the bank, cash or card account it left. Payee optional. Same governance as bills (agents: within policy it posts, otherwise a proposal; a first document for a payee is queued); dry_run previews.", "tags": [ "spending" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payee_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The vendor paid (optional)" }, "payment_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "The bank, cash or credit-card account the money left" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (EXP-0001) when omitted" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Receipt or confirmation number" }, "memo": { "type": "string", "maxLength": 500 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 199, "description": "What the money paid for: expense (or asset) accounts, or products and services (their purchase account and cost). No sales tax." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\\\u0000-\\u001f\\u007f]+$", "description": "The file's name, without a path" }, "content_type": { "type": "string", "pattern": "^[a-z]+/[A-Za-z0-9.+-]{1,80}$", "description": "Media type, e.g. image/jpeg or application/pdf" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 1073741824 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the file (lowercase hex): its fingerprint, to match a later upload or OCR run" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "file_name", "content_type", "size_bytes" ], "additionalProperties": false }, "maxItems": 10, "description": "Receipt metadata (the file itself is not stored)" }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "payment_account", "doc_date", "lines" ], "additionalProperties": false }, "example": { "payee_id": "00000000-0000-4000-8000-000000000000", "payment_account": "2100", "doc_date": "2026-10-04", "memo": "Printer toner", "lines": [ { "account": "6600", "amount_cents": 4299, "description": "Toner" } ], "attachments": [ { "file_name": "receipt.jpg", "content_type": "image/jpeg", "size_bytes": 182331 } ] } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/checks": { "post": { "operationId": "createCheck", "summary": "Record a check written (Dr the lines, Cr the bank or cash account it is drawn on); the number is the check number. Same governance as bills; dry_run previews.", "tags": [ "spending" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payee_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The vendor paid (optional)" }, "payment_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "The bank or cash account the check is drawn on" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "The check number (default: the highest check number so far + 1, 1001 for the first)" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Receipt or confirmation number" }, "memo": { "type": "string", "maxLength": 500 }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLineInput" }, "minItems": 1, "maxItems": 199, "description": "What the money paid for: expense (or asset) accounts, or products and services (their purchase account and cost). No sales tax." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\\\u0000-\\u001f\\u007f]+$", "description": "The file's name, without a path" }, "content_type": { "type": "string", "pattern": "^[a-z]+/[A-Za-z0-9.+-]{1,80}$", "description": "Media type, e.g. image/jpeg or application/pdf" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 1073741824 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the file (lowercase hex): its fingerprint, to match a later upload or OCR run" }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "file_name", "content_type", "size_bytes" ], "additionalProperties": false }, "maxItems": 10, "description": "Receipt metadata (the file itself is not stored)" }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "payment_account", "doc_date", "lines" ], "additionalProperties": false }, "example": { "payment_account": "1000", "doc_date": "2026-10-01", "number": "1042", "memo": "October rent", "lines": [ { "account": "6700", "amount_cents": 180000 } ] } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/transfers": { "post": { "operationId": "createTransfer", "summary": "Move money between two bank, cash or card accounts (Dr the account it arrives in, Cr the one it leaves), e.g. to savings or to pay the card. Same governance as any entry; dry_run previews.", "tags": [ "spending" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "from_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "The bank, cash or card account the money leaves" }, "to_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "The bank, cash or card account it arrives in" }, "amount_cents": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "transfer_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "number": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z._/-]{0,29}$", "description": "Optional; assigned (TRF-0001) when omitted" }, "reference": { "type": "string", "minLength": 1, "maxLength": 100 }, "memo": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "soft_lock_override_reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "from_account", "to_account", "amount_cents", "transfer_date" ], "additionalProperties": false }, "example": { "from_account": "1000", "to_account": "2100", "amount_cents": 125000, "transfer_date": "2026-10-05", "memo": "Pay the card" } } } }, "responses": { "200": { "description": "Dry run: the document, its number, the exact entry, policy verdict; nothing written", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "201": { "description": "Posted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "202": { "description": "Queued for approval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/documents/{id}/attachments": { "post": { "operationId": "addDocumentAttachment", "summary": "Record a receipt's or other file's metadata (name, type, size, SHA-256, note) on a posted document. The file itself is not stored; attachments are append-only. Audited; dry_run previews.", "tags": [ "spending" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^/\\\\\\u0000-\\u001f\\u007f]+$", "description": "The file's name, without a path" }, "content_type": { "type": "string", "pattern": "^[a-z]+/[A-Za-z0-9.+-]{1,80}$", "description": "Media type, e.g. image/jpeg or application/pdf" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 1073741824 }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "SHA-256 of the file (lowercase hex): its fingerprint, to match a later upload or OCR run" }, "note": { "type": "string", "maxLength": 500 }, "dry_run": { "type": "boolean" } }, "required": [ "file_name", "content_type", "size_bytes" ], "additionalProperties": false }, "example": { "file_name": "receipt-0412.jpg", "content_type": "image/jpeg", "size_bytes": 245112, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" } } } }, "responses": { "200": { "description": "Dry run", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" }, "document": { "$ref": "#/components/schemas/Document" }, "dry_run": { "type": "boolean" } }, "required": [ "attachment", "document" ] } } } }, "201": { "description": "Recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "attachment": { "$ref": "#/components/schemas/Attachment" }, "document": { "$ref": "#/components/schemas/Document" } }, "required": [ "attachment", "document" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/accounts/{code}/register": { "get": { "operationId": "getAccountRegister", "summary": "An account's register: every line in a date range with the running balance (natural sign), the document, payment or entry behind it, the other side of the entry and whether it is reconciled", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Register", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountRegister" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/search": { "get": { "operationId": "searchBooks", "summary": "Search these books: transactions by number, amount ($ or cents as dollars), memo, reference, line description or customer/vendor name; customers and vendors; products and services; accounts by code or name", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Results by group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/dashboard": { "get": { "operationId": "getDashboard", "summary": "Dashboard figures computed on the server: P&L this month and fiscal year to date, cash at the last 12 month-ends, AR and AP with what is overdue, and the bank accounts with unreconciled lines", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dashboard" } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/sales-by-customer": { "get": { "operationId": "getSalesByCustomer", "summary": "Sales by customer (income on invoices, sales receipts and credit memos, accrual), with what the P&L holds beyond them", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Sales by customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrExpensesByParty" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/sales-by-item": { "get": { "operationId": "getSalesByItem", "summary": "Sales by product or service: quantity and amount on invoices and sales receipts less credit memos (no tax lines), by document date; voids subtract on their date", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Sales by item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesByItem" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/expenses-by-vendor": { "get": { "operationId": "getExpensesByVendor", "summary": "Expenses by vendor (cost of sales and expense accounts on bills, vendor credits, expenses and checks, accrual), with what the P&L holds beyond them", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Expenses by vendor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SalesOrExpensesByParty" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/ar-detail": { "get": { "operationId": "getArDetail", "summary": "Receivables detail as of a date: every open invoice, unapplied credit memo and customer payment by customer, with the control-account tie-out", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Open documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenDocuments" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/ap-detail": { "get": { "operationId": "getApDetail", "summary": "Payables detail as of a date: every open bill, unapplied vendor credit and prepayment by vendor, with the control-account tie-out", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Open documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenDocuments" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/transaction-list": { "get": { "operationId": "getTransactionList", "summary": "Every posted entry in a date range by date: document, payment or journal entry, contact, accounts and amount", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000 } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/reports/1099-summary": { "get": { "operationId": "get1099Summary", "summary": "1099 summary for a calendar year: payments to vendors flagged for 1099s (bill payments, expenses and checks; card payments and refunds left out), whether each reaches the filing threshold and has a tax ID on file (last four digits only), and unflagged vendors to review. Filing is out of scope.", "tags": [ "reports" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "year", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1900, "maximum": 2999 } }, { "name": "threshold_cents", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "1099 summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary1099" } }, "text/csv": { "schema": { "type": "string", "description": "Same report as CSV (format=csv). Money as decimal dollars from integer cents." } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/healthz": { "get": { "operationId": "getHealthz", "summary": "Service health for the status page: {status: ok | degraded}. No details; CORS only for https://status.evenbead.com.", "tags": [ "meta" ], "security": [], "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "const": "ok" }, "service": { "type": "string" }, "time": { "type": "string" } }, "required": [ "status", "service", "time" ] } } } }, "503": { "description": "Degraded (the database is unreachable)" } } } }, "/v1/documents/{id}/email": { "post": { "operationId": "emailDocument", "summary": "Email an invoice, credit memo or sales receipt to the customer as a PDF (from noreply@evenbead.com with your company's name; Reply-To your address). An agent over its policy creates a proposal instead.", "tags": [ "email" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendRequest" }, "example": { "message": "Thanks for your business." } } } }, "responses": { "200": { "description": "Dry run: the preview and the policy verdict", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "const": true }, "email": { "type": "object", "properties": {} }, "policy": { "type": "object", "properties": {} } }, "required": [ "dry_run" ] } } } }, "201": { "description": "Email queued (or, for an agent over its policy, waiting for approval: status pending_approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" }, "policy": { "type": "object", "properties": {} } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/estimates/{id}/email": { "post": { "operationId": "emailEstimate", "summary": "Email an estimate to the customer as a PDF. Same governance as emailDocument.", "tags": [ "email" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSendRequest" } } } }, "responses": { "200": { "description": "Dry run: the preview and the policy verdict", "content": { "application/json": { "schema": { "type": "object", "properties": { "dry_run": { "const": true }, "email": { "type": "object", "properties": {} }, "policy": { "type": "object", "properties": {} } }, "required": [ "dry_run" ] } } } }, "201": { "description": "Email queued (or, for an agent over its policy, waiting for approval: status pending_approval)", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" }, "policy": { "type": "object", "properties": {} } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/email/outbox": { "get": { "operationId": "listEmails", "summary": "This company's emails, newest first (documents, reminders, security notices), with delivery status", "tags": [ "email" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending_approval", "queued", "sending", "sent", "failed", "suppressed", "rejected", "cancelled" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Email" } } }, "required": [ "emails" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/email/outbox/{id}": { "get": { "operationId": "getEmail", "summary": "One email with its delivery status", "tags": [ "email" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Email", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/email/outbox/{id}/approve": { "post": { "operationId": "approveEmail", "summary": "Approve an agent's email that waits for approval (approve scope; never your own); it is queued for sending", "tags": [ "email" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Approved and queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/email/outbox/{id}/reject": { "post": { "operationId": "rejectEmail", "summary": "Reject an agent's email that waits for approval, with a reason (approve scope; never your own)", "tags": [ "email" ], "security": [ { "apiKey": [ "approve" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Rejected", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "approve" } }, "/v1/email/outbox/{id}/cancel": { "post": { "operationId": "cancelEmail", "summary": "Cancel an email that has not been sent yet (its requester, or an admin)", "tags": [ "email" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/email/outbox/{id}/retry": { "post": { "operationId": "retryEmail", "summary": "Queue a failed email again (admin scope)", "tags": [ "email" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Queued again", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "$ref": "#/components/schemas/Email" } }, "required": [ "email" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/email/settings": { "get": { "operationId": "getEmailSettings", "summary": "This company's email settings: Reply-To, sender name, security-notice address, payment reminders", "tags": [ "email" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/EmailSettings" } }, "required": [ "settings" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" }, "post": { "operationId": "updateEmailSettings", "summary": "Set Reply-To, sender name, the security-notice address and payment reminders (off by default; days relative to the due date, e.g. [3, 10, 30]). Admin scope.", "tags": [ "email" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Not needed: this write sets a value, so repeating it leaves the same state." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reply_to": { "type": [ "string", "null" ], "maxLength": 254, "pattern": "^[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+@[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+\\.[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+$", "description": "An email address." }, "display_name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "pattern": "^[^\\r\\n<>\"]*$" }, "security_notices_to": { "type": [ "string", "null" ], "maxLength": 254, "pattern": "^[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+@[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+\\.[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+$", "description": "An email address." }, "reminders_enabled": { "type": "boolean" }, "reminder_days": { "type": "array", "items": { "type": "integer", "minimum": -30, "maximum": 365 }, "minItems": 1, "maxItems": 6 } }, "additionalProperties": false }, "example": { "reply_to": "billing@example.com", "reminders_enabled": true, "reminder_days": [ 3, 10, 30 ] } } } }, "responses": { "200": { "description": "Settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "$ref": "#/components/schemas/EmailSettings" } }, "required": [ "settings" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/email/suppressions": { "get": { "operationId": "listEmailSuppressions", "summary": "Addresses this company's emails are not sent to (unsubscribed from reminders, or bounced)", "tags": [ "email" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Suppressions", "content": { "application/json": { "schema": { "type": "object", "properties": { "suppressions": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSuppression" } } }, "required": [ "suppressions" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-feeds": { "get": { "operationId": "listBankFeeds", "summary": "Bank feeds (Plaid connections) with their accounts, status and last sync, plus whether feeds are configured on this deployment and the plan's limit on feed-connected bank accounts", "tags": [ "banking" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Feeds", "content": { "application/json": { "schema": { "type": "object", "properties": { "configured": { "type": "boolean" }, "environment": { "type": [ "string", "null" ], "enum": [ "sandbox", "production" ] }, "usage": { "type": "object", "properties": { "plan": { "type": "string" }, "connected": { "type": "integer" }, "limit": { "type": [ "integer", "null" ], "description": "null: unlimited" } }, "required": [ "plan", "connected", "limit" ] }, "bank_feeds": { "type": "array", "items": { "$ref": "#/components/schemas/BankFeed" } } }, "required": [ "configured", "environment", "usage", "bank_feeds" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" }, "post": { "operationId": "connectBankFeed", "summary": "Finish connecting a bank: exchange Plaid Link's public_token, store the access token sealed, list the bank's accounts. Nothing is imported until an account is linked to a bank account. People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_token": { "type": "string", "pattern": "^public-(sandbox|production|development)-[A-Za-z0-9-]{8,100}$" } }, "required": [ "public_token" ], "additionalProperties": false }, "example": { "public_token": "public-sandbox-00000000-0000-0000-0000-000000000000" } } } }, "responses": { "201": { "description": "Connected", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Plaid refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-feeds/{id}": { "get": { "operationId": "getBankFeed", "summary": "One bank feed with its accounts and health", "tags": [ "banking" ], "security": [ { "apiKey": [ "read" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Feed", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "read" } }, "/v1/bank-feeds/link-token": { "post": { "operationId": "createBankFeedLinkToken", "summary": "A short-lived Plaid Link token to connect a bank in the browser, or (with bank_feed_id) to reconnect one in update mode. People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "Reconnect this feed (Link update mode)" }, "account_selection": { "type": "boolean", "description": "Update mode: let the person add or remove accounts" } }, "additionalProperties": false }, "example": {} } } }, "responses": { "201": { "description": "Link token (shown once; null on an idempotent replay)", "content": { "application/json": { "schema": { "type": "object", "properties": { "link_token": { "type": [ "string", "null" ] }, "expiration": { "type": "string" }, "mode": { "type": "string", "enum": [ "create", "update" ] }, "oauth_redirect": { "type": "boolean", "description": "Whether OAuth banks redirect back to /app/banking/plaid/oauth" } }, "required": [ "link_token", "expiration", "mode", "oauth_redirect" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Plaid refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-feeds/{id}/accounts/link": { "post": { "operationId": "linkBankFeedAccount", "summary": "Feed one account at the bank into an existing bank account, or into a new bank account on a ledger account. Counts against the plan (Solo 3, Business 15, Advanced unlimited feed-connected bank accounts). Lines dated before import_from are not imported (default: the day after the last line imported from a file, else 24 months back); overlap with file imports is deduped. The next sync replays the history for it. People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The bank-feed account (BankFeedAccount.id)" }, "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "An existing Evenbead bank account" }, "new_bank_account": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "ledger_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, "required": [ "name", "ledger_account" ], "additionalProperties": false }, "import_from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, "required": [ "account" ], "additionalProperties": false }, "example": { "account": "6f1c1d2e-0000-4000-8000-000000000001", "bank_account_id": "6f1c1d2e-0000-4000-8000-000000000002" } } } }, "responses": { "200": { "description": "Linked", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-feeds/{id}/accounts/unlink": { "post": { "operationId": "unlinkBankFeedAccount", "summary": "Stop feeding a bank account from this connection (its lines stay; file import still works). People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "account": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "account", "reason" ], "additionalProperties": false }, "example": { "account": "6f1c1d2e-0000-4000-8000-000000000001", "reason": "closed account" } } } }, "responses": { "200": { "description": "Unlinked", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-feeds/{id}/sync": { "post": { "operationId": "syncBankFeed", "summary": "Pull new, changed and removed transactions now (Plaid /transactions/sync from the stored cursor) and import posted ones as bank lines. Agents may call it. A replay just syncs again (nothing new: nothing changes).", "tags": [ "banking" ], "security": [ { "apiKey": [ "propose" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Not needed: this write sets a value, so repeating it leaves the same state." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Sync result (login_required / error: reconnect or try later; the feed's status says which)", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "$ref": "#/components/schemas/BankFeedSync" }, "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "sync", "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "propose" } }, "/v1/bank-feeds/{id}/reconnected": { "post": { "operationId": "reconnectedBankFeed", "summary": "After Link update mode succeeded: refresh the connection's health and accounts at Plaid and ask for a sync. People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "Refreshed", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Plaid refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-feeds/{id}/settings": { "post": { "operationId": "updateBankFeedSettings", "summary": "Feed settings: include_pending imports pending transactions too (default off: posted only; a posted transaction then replaces its pending line). Changing it replays the history. People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Not needed: this write sets a value, so repeating it leaves the same state." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "include_pending": { "type": "boolean" } }, "required": [ "include_pending" ], "additionalProperties": false }, "example": { "include_pending": false } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } }, "/v1/bank-feeds/{id}/disconnect": { "post": { "operationId": "disconnectBankFeed", "summary": "Disconnect a bank: the connection is removed at Plaid (/item/remove) and its access token wiped here; linked bank accounts go back to file import; imported lines stay. Final. People only: agents are refused (insufficient_scope).", "tags": [ "banking" ], "security": [ { "apiKey": [ "admin" ] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200 }, "description": "Required on every write (except a dry run). Replays return the original result; reuse with a different request is 409 idempotency_conflict." }, { "name": "X-Evenbead-Company", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Firm keys and firm sessions only (ADR-0014): the client company to act in. The caller acts as its firm identity inside that company, within the client's grant." }, { "name": "X-Agent-Model", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Model name and version of the acting agent. Required for agent keys on writes; recorded in the audit log." }, { "name": "X-Agent-Run-Id", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "reason" ], "additionalProperties": false }, "example": { "reason": "switched banks" } } } }, "responses": { "200": { "description": "Disconnected", "content": { "application/json": { "schema": { "type": "object", "properties": { "bank_feed": { "$ref": "#/components/schemas/BankFeed" } }, "required": [ "bank_feed" ] } } } }, "400": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Error (see error.type)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Plaid refused or failed (error.type upstream_error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "admin" } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "unbalanced", "posted_immutable", "period_locked", "period_missing", "period_soft_locked", "account_inactive", "account_not_found", "account_has_postings", "audit_append_only", "idempotency_conflict", "proposal_not_pending", "invalid_reversal", "already_reversed", "period_overlap", "reopen_requires_reason", "actor_context_required", "revocation_final", "invalid_reference", "duplicate", "not_found", "validation_error", "permission_denied", "invalid_json", "idempotency_key_required", "model_required", "unauthorized", "key_revoked", "insufficient_scope", "agent_writes_suspended", "self_approval_forbidden", "method_not_allowed", "payload_too_large", "internal_error", "class_not_found", "bank_feed_immutable", "bank_line_state", "reconciliation_invalid", "reconciliation_finished", "reconciliation_difference", "unsupported_format", "control_account", "document_invalid", "document_void", "over_applied", "fiscal_year_locked", "session_invalid", "reconciliation_undo", "contact_not_found", "item_not_found", "migration_invalid", "connection_invalid", "not_configured", "estimate_invalid", "tax_invalid", "recurring_invalid", "migration_invalid", "connection_invalid", "not_configured", "firm_invalid", "firm_access_denied", "company_required", "close_invalid", "close_incomplete", "budget_exceeded", "upstream_error", "key_expired", "rate_limited", "credential_invalid", "actor_unverified", "invite_invalid", "account_protected", "chart_not_empty", "email_invalid", "admin_unbound", "account_suspended", "feature_disabled", "bank_feed_invalid", "plan_limit" ], "description": "Stable machine-readable error type." }, "message": { "type": "string" }, "details": { "type": "object" }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } } }, "required": [ "type", "message" ] } }, "required": [ "error" ] }, "ValidationIssue": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "line_no": { "type": "integer" } }, "required": [ "type", "message" ] }, "Company": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "base_currency": { "type": "string" }, "agent_writes_suspended": { "type": "boolean" }, "fiscal_year_start_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Fiscal year start (1 = January). A fiscal year is named by the year it ends." }, "plan": { "type": "string", "enum": [ "solo", "business", "advanced", "owned" ], "description": "ADR-0009 plan; sets the API rate limit (Solo 60, Business 300, Advanced 1,200 requests/min; Owned: the operator's setting)." } }, "required": [ "id", "name", "base_currency", "agent_writes_suspended", "fiscal_year_start_month" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "cpa", "accountant", "staff" ] } }, "required": [ "id", "name", "role" ] }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "owner_user_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "posting_threshold_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "name", "owner_user_id", "scopes", "posting_threshold_cents", "revoked_at" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "key_prefix": { "type": "string" }, "principal_type": { "type": "string", "enum": [ "user", "agent" ] }, "user_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agent_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "expires_at": { "type": "string", "description": "The key stops working at this time (refused by the API and the database)." }, "last_used_at": { "type": [ "string", "null" ], "description": "Last request (recorded at most once a minute)." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the company plan's limit)." }, "rotated_from_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The key this one replaced." }, "rotated_at": { "type": [ "string", "null" ], "description": "When this key was rotated (it then expires at the end of the overlap)." }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "key_prefix", "principal_type", "user_id", "agent_id", "scopes", "revoked_at", "expires_at", "last_used_at", "rate_limit_rpm", "status" ] }, "IssuedKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "key": { "type": [ "string", "null" ], "description": "The secret, shown ONCE. null on an idempotent replay (secrets are never stored)." }, "key_prefix": { "type": "string" }, "principal_type": { "type": "string", "enum": [ "user", "agent" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "key", "key_prefix", "principal_type", "scopes" ] }, "NewApiKey": { "type": "object", "properties": { "api_key": { "$ref": "#/components/schemas/IssuedKey" } }, "required": [ "api_key" ] }, "Account": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "asset", "liability", "equity", "income", "expense" ] }, "subtype": { "type": [ "string", "null" ] }, "parent_code": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "control": { "type": [ "string", "null" ], "enum": [ "ar", "ap", null ], "description": "AR/AP control account: posted only through invoices, bills, credits and payments." }, "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Natural balance (debit-normal for assets and expenses, credit-normal otherwise); only with include_balances=true." } }, "required": [ "id", "code", "name", "type", "subtype", "parent_code", "active" ] }, "DefaultAccounts": { "type": "object", "properties": { "income": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Where a new invoice, credit memo, sales receipt or estimate line posts unless another account is chosen" }, "expense": { "type": [ "string", "null" ], "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Where a new bill or vendor credit line posts unless another account is chosen" } }, "required": [ "income", "expense" ] }, "StarterChart": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart)." }, "name": { "type": "string" }, "description": { "type": "string" }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "name": { "type": "string" }, "type": { "type": "string" }, "subtype": { "type": [ "string", "null" ] }, "control": { "type": "string", "enum": [ "ar", "ap" ] } }, "required": [ "code", "name", "type" ] } }, "defaults": { "$ref": "#/components/schemas/DefaultAccounts" }, "bank_accounts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "ledger_account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" } }, "required": [ "name", "kind", "ledger_account" ] } } }, "required": [ "id", "name", "description", "accounts", "defaults", "bank_accounts" ] }, "CompanySetup": { "type": "object", "properties": { "starter_chart": { "type": "string", "enum": [ "general", "services", "retail", "empty" ], "description": "Starter chart of accounts: general small business (default), services/agency, retail/product, or empty (migrations bring their own chart)." }, "accounts": { "type": "integer", "minimum": 0 }, "bank_accounts": { "type": "integer", "minimum": 0, "description": "Bank and card accounts registered (Checking, Savings, Credit Card)" }, "periods": { "type": "integer", "minimum": 0, "description": "Monthly periods created: this fiscal year and the next" } }, "required": [ "starter_chart", "accounts", "bank_accounts", "periods" ] }, "Period": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "status": { "type": "string", "enum": [ "open", "soft_locked", "hard_locked" ] }, "fiscal_year": { "type": "integer" } }, "required": [ "id", "start_date", "end_date", "status" ] }, "DraftLine": { "type": "object", "properties": { "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Account code." }, "debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "memo": { "type": "string", "maxLength": 500 }, "class": { "type": "string", "pattern": "^\\S(.{0,58}\\S)?$", "description": "Class name (reporting dimension)." } }, "required": [ "account" ], "additionalProperties": false }, "EntryLine": { "type": "object", "properties": { "line_no": { "type": "integer", "minimum": 1 }, "account_code": { "type": "string" }, "account_name": { "type": "string" }, "debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "memo": { "type": "string" }, "class": { "type": [ "string", "null" ] } }, "required": [ "line_no", "account_code", "account_name", "debit_cents", "credit_cents", "memo" ] }, "NormalizedEntry": { "type": "object", "properties": { "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/EntryLine" } } }, "required": [ "entry_date", "memo", "lines" ] }, "JournalEntry": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entry_no": { "type": "integer" }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string" }, "period_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source": { "type": "string", "enum": [ "api", "proposal", "reversal", "import" ] }, "reverses_entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "actor_type": { "type": "string", "enum": [ "user", "agent", "system" ] }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "approved_by_type": { "type": [ "string", "null" ] }, "approved_by_id": { "type": [ "string", "null" ] }, "posted_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/EntryLine" } } }, "required": [ "id", "entry_no", "entry_date", "memo", "period_id", "source", "actor_type", "actor_id", "posted_at", "lines" ] }, "Policy": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "auto_post", "queue", "post" ] }, "reasons": { "type": "array", "items": { "type": "string", "enum": [ "over_threshold", "sensitive_account", "period_soft_locked", "low_confidence", "new_counterparty" ] } }, "threshold_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "verdict", "reasons", "total_cents" ] }, "Proposal": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agent_name": { "type": "string" }, "model": { "type": "string" }, "run_id": { "type": [ "string", "null" ] }, "draft": { "$ref": "#/components/schemas/NormalizedEntry" }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "policy": { "$ref": "#/components/schemas/Policy" }, "status": { "type": "string", "enum": [ "pending", "auto_posted", "approved", "rejected" ] }, "approver_type": { "type": [ "string", "null" ] }, "approver_id": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "decision_reason": { "type": [ "string", "null" ] }, "journal_entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "action": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document.create", "payment.create", "refund.create" ] }, "request": { "type": "object" } }, "required": [ "type", "request" ] } ], "description": "For an invoice, bill, credit or payment proposal: the request the approval executes. null for plain entries." } }, "required": [ "id", "agent_id", "agent_name", "model", "draft", "total_cents", "policy", "status", "created_at" ] }, "ProposeResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "posted", "pending_approval", "dry_run" ] }, "valid": { "type": "boolean" }, "would": { "type": "string", "enum": [ "post", "queue_for_approval", "be_refused" ] }, "policy": { "$ref": "#/components/schemas/Policy" }, "period": { "$ref": "#/components/schemas/Period", "type": [ null, "null" ] }, "entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "$ref": "#/components/schemas/NormalizedEntry" }, { "type": "null" } ] }, "proposal": { "$ref": "#/components/schemas/Proposal" }, "affected_balances": { "type": "array", "items": { "type": "object", "properties": { "account_code": { "type": "string" }, "before_cents": { "type": "integer" }, "after_cents": { "type": "integer" } }, "required": [ "account_code", "before_cents", "after_cents" ] } }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } }, "bank_line": { "$ref": "#/components/schemas/BankLine" } }, "required": [ "outcome" ] }, "TrialBalance": { "type": "object", "properties": { "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "account_code": { "type": "string" }, "account_name": { "type": "string" }, "type": { "type": "string" }, "debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "account_code", "account_name", "type", "debit_cents", "credit_cents" ] } }, "total_debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "total_credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "balanced": { "type": "boolean" } }, "required": [ "as_of", "rows", "total_debit_cents", "total_credit_cents", "balanced" ] }, "AuditVerdict": { "type": "object", "properties": { "ok": { "type": "boolean" }, "events": { "type": "integer" }, "head_hash": { "type": "string" }, "first_bad_seq": { "type": [ "integer", "null" ] }, "problem": { "type": [ "string", "null" ] } }, "required": [ "ok", "events", "head_hash", "first_bad_seq", "problem" ] }, "AuditEvent": { "type": "object", "properties": { "seq": { "type": "integer" }, "occurred_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "run_id": { "type": [ "string", "null" ] }, "action": { "type": "string" }, "target_type": { "type": [ "string", "null" ] }, "target_id": { "type": [ "string", "null" ] }, "before": {}, "after": {}, "meta": {}, "hash": { "type": "string" } }, "required": [ "seq", "occurred_at", "actor_type", "actor_id", "action", "hash" ] }, "Class": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "name", "active" ] }, "CsvProfile": { "type": "object", "properties": { "delimiter": { "type": "string", "enum": [ ",", ";", "\t", "|" ] }, "has_header": { "type": "boolean" }, "skip_rows": { "type": "integer", "minimum": 0, "maximum": 50 }, "date": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "date_format": { "type": "string", "enum": [ "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MM/DD/YY", "YYYYMMDD", "DD.MM.YYYY" ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, { "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "minItems": 1, "maxItems": 5 } ] }, "amount": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "amount_sign": { "type": "string", "enum": [ "deposit_positive", "withdrawal_positive" ] }, "money_in": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "money_out": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "payee": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "fitid": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "balance": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "check_no": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "integer", "minimum": 0, "maximum": 499 } ] }, "decimal_separator": { "type": "string", "enum": [ ".", "," ] } }, "required": [ "date", "date_format", "description" ], "additionalProperties": false }, "BankAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "checking", "savings", "credit_card", "other" ] }, "ledger_account_code": { "type": "string" }, "ledger_account_name": { "type": "string" }, "ledger_account_type": { "type": "string", "enum": [ "asset", "liability" ] }, "institution": { "type": [ "string", "null" ] }, "mask": { "type": [ "string", "null" ] }, "provider": { "type": "string", "enum": [ "file", "plaid" ], "description": "file: OFX/QFX/CSV imports only; plaid: fed by a Plaid bank feed (file import still works)" }, "csv_profile": { "anyOf": [ { "$ref": "#/components/schemas/CsvProfile" }, { "type": "null" } ] }, "ledger_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "counts": { "type": "object", "properties": { "unmatched": { "type": "integer" }, "proposed": { "type": "integer" }, "matched": { "type": "integer" }, "categorized": { "type": "integer" }, "excluded": { "type": "integer" } } }, "last_reconciliation": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "statement_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "statement_ending_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "id", "statement_date", "statement_ending_balance_cents" ] }, { "type": "null" } ] }, "open_reconciliation_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "latest_statement": { "anyOf": [ { "type": "object", "properties": { "ledger_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ledger_balance_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, "required": [ "ledger_balance_cents", "ledger_balance_date" ] }, { "type": "null" } ] } }, "required": [ "id", "name", "kind", "ledger_account_code", "ledger_account_name", "ledger_account_type", "institution", "mask", "provider" ] }, "BankImport": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "format": { "type": "string", "enum": [ "ofx", "csv", "provider" ] }, "filename": { "type": [ "string", "null" ] }, "file_sha256": { "type": "string" }, "lines_total": { "type": "integer" }, "lines_new": { "type": "integer" }, "lines_duplicate": { "type": "integer" }, "statement_start": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "statement_end": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "ledger_balance_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ledger_balance_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "bank_account_id", "format", "file_sha256", "lines_total", "lines_new", "lines_duplicate" ] }, "RuleSuggestion": { "type": "object", "properties": { "rule_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "rule_name": { "type": "string" }, "account": { "type": "string" }, "class": { "type": [ "string", "null" ] }, "memo": { "type": [ "string", "null" ] } }, "required": [ "rule_id", "rule_name", "account" ] }, "BankLine": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "import_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "posted_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed cents: + money in, - money out (holder's side, as the bank reports it)." }, "description": { "type": "string" }, "payee": { "type": [ "string", "null" ] }, "check_no": { "type": [ "string", "null" ] }, "fitid": { "type": [ "string", "null" ] }, "natural_key": { "type": "string" }, "running_balance_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "status": { "type": "string", "enum": [ "unmatched", "proposed", "matched", "categorized", "excluded" ] }, "link_kind": { "type": [ "string", "null" ], "enum": [ "match", "categorize", "transfer", null ] }, "entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "excluded_reason": { "type": [ "string", "null" ] }, "suggestion": { "anyOf": [ { "$ref": "#/components/schemas/RuleSuggestion" }, { "type": "null" } ] } }, "required": [ "id", "bank_account_id", "posted_date", "amount_cents", "description", "status", "natural_key" ] }, "BankRule": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "priority": { "type": "integer" }, "bank_account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "payee_contains": { "type": [ "string", "null" ] }, "direction": { "type": "string", "enum": [ "in", "out", "any" ] }, "amount_min_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "amount_max_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "account": { "type": "string" }, "class": { "type": [ "string", "null" ] }, "memo": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } }, "required": [ "id", "name", "priority", "direction", "account", "active" ] }, "AutoMatchResult": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "matched": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "days_apart": { "type": "number" }, "confidence": { "type": "number" } }, "required": [ "line_id", "entry_id" ] } }, "transfers": { "type": "array", "items": { "type": "object", "properties": { "out_line_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "in_line_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "outcome": { "type": "string" }, "entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "out_line_id", "in_line_id", "amount_cents" ] } }, "ambiguous": { "type": "array", "items": { "type": "object", "properties": { "line_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "line_id" ] } } }, "required": [ "dry_run", "matched", "transfers", "ambiguous" ] }, "Reconciliation": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "statement_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "statement_ending_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "beginning_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "cleared_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "difference_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "items": { "type": "integer" }, "status": { "type": "string", "enum": [ "in_progress", "finished", "undone" ] }, "previous_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "started_by_type": { "type": "string" }, "started_by_id": { "type": "string" }, "finished_by_type": { "type": [ "string", "null" ] }, "finished_by_id": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "undone_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "undone_by_type": { "type": [ "string", "null" ] }, "undone_by_id": { "type": [ "string", "null" ] }, "undo_reason": { "type": [ "string", "null" ] } }, "required": [ "id", "bank_account_id", "statement_date", "statement_ending_balance_cents", "beginning_balance_cents", "cleared_cents", "difference_cents", "status" ] }, "ReconLine": { "type": "object", "properties": { "journal_line_id": { "type": "integer" }, "entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entry_no": { "type": "integer" }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "bank_line_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "bank_posted_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "bank_description": { "type": [ "string", "null" ] } }, "required": [ "journal_line_id", "entry_id", "entry_no", "entry_date", "memo", "amount_cents" ] }, "ReconciliationDetail": { "type": "object", "properties": { "reconciliation": { "$ref": "#/components/schemas/Reconciliation" }, "bank_account": { "$ref": "#/components/schemas/BankAccount" }, "cleared": { "type": "array", "items": { "$ref": "#/components/schemas/ReconLine" } }, "uncleared": { "type": "array", "items": { "$ref": "#/components/schemas/ReconLine" } } }, "required": [ "reconciliation", "bank_account", "cleared", "uncleared" ] }, "ReconciliationReport": { "type": "object", "properties": { "reconciliation": { "$ref": "#/components/schemas/Reconciliation" }, "bank_account": { "$ref": "#/components/schemas/BankAccount" }, "cleared_deposits": { "type": "array", "items": { "$ref": "#/components/schemas/ReconLine" } }, "cleared_payments": { "type": "array", "items": { "$ref": "#/components/schemas/ReconLine" } }, "cleared_deposits_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "cleared_payments_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "uncleared": { "type": "array", "items": { "$ref": "#/components/schemas/ReconLine" } }, "uncleared_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ledger_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ties_out": { "type": "boolean" } }, "required": [ "reconciliation", "bank_account", "cleared_deposits", "cleared_payments", "uncleared", "ledger_balance_cents", "ties_out" ] }, "StatementRow": { "type": "object", "properties": { "account_code": { "type": "string" }, "account_name": { "type": "string" }, "type": { "type": "string" }, "subtype": { "type": [ "string", "null" ] }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "account_code", "account_name", "type", "amount_cents" ] }, "ProfitAndLoss": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "class": { "type": [ "string", "null" ] }, "basis": { "type": "string", "enum": [ "accrual", "cash" ] }, "income": { "type": "array", "items": { "$ref": "#/components/schemas/StatementRow" } }, "cost_of_goods_sold": { "type": "array", "items": { "$ref": "#/components/schemas/StatementRow" } }, "expenses": { "type": "array", "items": { "$ref": "#/components/schemas/StatementRow" } }, "total_income_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_cogs_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "gross_profit_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_expenses_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "net_income_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "from", "to", "income", "cost_of_goods_sold", "expenses", "total_income_cents", "total_cogs_cents", "gross_profit_cents", "total_expenses_cents", "net_income_cents" ] }, "BalanceSheet": { "type": "object", "properties": { "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "fiscal_year_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "basis": { "const": "accrual" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/StatementRow" } }, "liabilities": { "type": "array", "items": { "$ref": "#/components/schemas/StatementRow" } }, "equity": { "type": "array", "items": { "$ref": "#/components/schemas/StatementRow" } }, "retained_earnings_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "current_year_earnings_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_assets_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_liabilities_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_equity_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_liabilities_and_equity_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "balanced": { "type": "boolean" } }, "required": [ "as_of", "assets", "liabilities", "equity", "retained_earnings_cents", "current_year_earnings_cents", "total_assets_cents", "total_liabilities_and_equity_cents", "balanced" ] }, "GeneralLedger": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "account": { "type": [ "string", "null" ] }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "account_code": { "type": "string" }, "account_name": { "type": "string" }, "type": { "type": "string" }, "opening_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entry_no": { "type": "integer" }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "entry_memo": { "type": "string" }, "line_memo": { "type": "string" }, "class": { "type": [ "string", "null" ] }, "debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "entry_id", "entry_no", "entry_date", "debit_cents", "credit_cents", "balance_cents" ] } }, "total_debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "total_credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "closing_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "account_code", "account_name", "opening_balance_cents", "lines", "closing_balance_cents" ] } } }, "required": [ "from", "to", "accounts" ] }, "TaxTrialBalance": { "type": "object", "properties": { "format": { "const": "evenbead-tb-generic/1" }, "company": { "type": "string" }, "period_start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "period_end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "basis": { "const": "accrual" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "account_code": { "type": "string" }, "account_name": { "type": "string" }, "account_type": { "type": "string" }, "account_subtype": { "type": [ "string", "null" ] }, "debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "tax_line": { "type": [ "string", "null" ] } }, "required": [ "account_code", "account_name", "account_type", "debit_cents", "credit_cents" ] } }, "total_debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "total_credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "balanced": { "type": "boolean" }, "csv_sha256": { "type": "string" } }, "required": [ "format", "period_start", "period_end", "rows", "total_debit_cents", "total_credit_cents", "balanced" ] }, "Health": { "type": "object", "properties": { "ok": { "type": "boolean" }, "service": { "const": "evenbead-agent-surface" } }, "required": [ "ok", "service" ] }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "customer", "vendor" ] }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "terms_days": { "type": "integer" }, "active": { "type": "boolean" }, "open_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Open documents less unapplied credits" }, "overdue_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "documents_open": { "type": "integer" }, "is_1099": { "type": "boolean", "description": "Vendors: gets a 1099 (contractor, attorney, rent)" }, "tax_id_on_file": { "type": "boolean", "description": "A tax ID was recorded (only its last four digits are kept)" }, "tax_id_last4": { "type": [ "string", "null" ], "pattern": "^[0-9]{4}$", "description": "Last four digits of the vendor's tax ID; the full number is never stored" } }, "required": [ "id", "kind", "name", "email", "terms_days", "active" ] }, "Item": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "service", "non_inventory" ] }, "description": { "type": "string" }, "sales_price_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "purchase_cost_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "income_account": { "type": [ "string", "null" ] }, "expense_account": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "taxable": { "type": "boolean", "description": "Lines with this item are taxable by default (when the document has a tax rate)" } }, "required": [ "id", "name", "kind", "sales_price_cents", "purchase_cost_cents", "income_account", "expense_account", "active" ] }, "DocumentLineInput": { "type": "object", "properties": { "item_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "An item: supplies the account, description and price unless given." }, "description": { "type": "string", "maxLength": 500 }, "account": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Income account (sales) or expense/asset account (purchases); not a control account." }, "class": { "type": "string", "pattern": "^\\S(.{0,58}\\S)?$", "description": "Class name (reporting dimension)." }, "quantity": { "anyOf": [ { "type": "number", "minimum": 0.0001, "maximum": 9999999999 }, { "type": "string", "pattern": "^\\d{1,10}(\\.\\d{1,4})?$" } ], "description": "Up to 4 decimals; default 1." }, "unit_price_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Line amount; with no unit price it is the amount for quantity 1. Must equal round(quantity × unit price) when both are given." }, "taxable": { "type": "boolean", "description": "Sales tax applies to this line (needs the document's tax_rate_id; default: the item's taxable flag)" } }, "additionalProperties": false }, "DocumentLine": { "type": "object", "properties": { "line_no": { "type": "integer" }, "item_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "item_name": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "account_code": { "type": "string" }, "account_name": { "type": "string" }, "class": { "type": [ "string", "null" ] }, "quantity": { "type": "string", "description": "Exact decimal" }, "unit_price_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "taxable": { "type": "boolean" }, "is_tax": { "type": "boolean", "description": "A sales-tax line (one per jurisdiction; posts to that rate's payable account)" }, "tax_rate_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "A tax line: the single-agency rate (jurisdiction) it collects" } }, "required": [ "line_no", "description", "account_code", "quantity", "unit_price_cents", "amount_cents" ] }, "DocumentTaxComponent": { "type": "object", "properties": { "rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "rate_name": { "type": "string" }, "rate_ppm": { "type": "integer" }, "agency_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agency_name": { "type": "string" }, "payable_account_code": { "type": "string" }, "tax_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "rate_id", "rate_name", "rate_ppm", "agency_id", "agency_name", "payable_account_code", "tax_cents" ] }, "Application": { "type": "object", "properties": { "id": { "type": "integer" }, "source_type": { "type": "string", "enum": [ "payment", "credit" ] }, "source_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source_number": { "type": "string" }, "document_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "document_number": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "applied_on": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "live": { "type": "boolean", "description": "false once the payment or credit is void" } }, "required": [ "id", "source_type", "source_id", "document_id", "amount_cents", "applied_on", "live" ] }, "DocumentSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "invoice", "credit_memo", "bill", "vendor_credit", "sales_receipt", "refund", "vendor_refund", "expense", "check", "transfer" ] }, "number": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "null: an expense or check without a payee, or a transfer" }, "contact_name": { "type": [ "string", "null" ] }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer" }, "reference": { "type": [ "string", "null" ] }, "memo": { "type": "string" }, "control_account_code": { "type": "string" }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "applied_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "open_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "status": { "type": "string", "enum": [ "open", "partial", "paid", "applied", "void" ] }, "days_overdue": { "type": "integer" }, "journal_entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "void_entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "void_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "void_reason": { "type": [ "string", "null" ] }, "subtotal_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "tax_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "tax_rate_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "tax_rate_name": { "type": [ "string", "null" ] }, "tax_rate_ppm": { "type": [ "integer", "null" ] }, "estimate_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "id", "kind", "number", "contact_id", "contact_name", "doc_date", "due_date", "total_cents", "open_cents", "status" ] }, "Document": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "invoice", "credit_memo", "bill", "vendor_credit", "sales_receipt", "refund", "vendor_refund", "expense", "check", "transfer" ] }, "number": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "null: an expense or check without a payee, or a transfer" }, "contact_name": { "type": [ "string", "null" ] }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "terms_days": { "type": "integer" }, "reference": { "type": [ "string", "null" ] }, "memo": { "type": "string" }, "control_account_code": { "type": "string" }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "applied_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "open_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "status": { "type": "string", "enum": [ "open", "partial", "paid", "applied", "void" ] }, "journal_entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "void_entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "void_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "void_reason": { "type": [ "string", "null" ] }, "subtotal_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "tax_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "tax_rate_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "tax_rate_name": { "type": [ "string", "null" ] }, "tax_rate_ppm": { "type": [ "integer", "null" ] }, "estimate_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLine" } }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } }, "tax_components": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentTaxComponent" }, "description": "The tax per jurisdiction (agency), from the document's tax lines" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" }, "description": "Receipt and file metadata recorded on the document (the files themselves are not stored)" } }, "required": [ "id", "kind", "number", "contact_id", "doc_date", "due_date", "total_cents", "open_cents", "status", "journal_entry_id", "lines", "applications" ] }, "DocumentPreview": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "invoice", "credit_memo", "bill", "vendor_credit", "sales_receipt", "refund", "vendor_refund", "expense", "check", "transfer" ] }, "number": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": [ "string", "null" ] }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLine" } } }, "required": [ "kind", "number", "doc_date", "due_date", "total_cents", "lines" ] }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "received", "made" ] }, "number": { "type": "string" }, "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "payment_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "account_code": { "type": "string" }, "account_name": { "type": "string" }, "control_account_code": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "memo": { "type": "string" }, "status": { "type": "string", "enum": [ "posted", "void" ] }, "journal_entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "void_entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "void_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "void_reason": { "type": [ "string", "null" ] }, "applied_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "unapplied_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Credit on account (deposit, overpayment, prepayment): apply it later or refund it" }, "applications": { "type": "array", "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "id", "kind", "number", "contact_id", "payment_date", "amount_cents", "account_code", "status", "journal_entry_id" ] }, "DocumentResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "posted", "pending_approval", "dry_run" ] }, "valid": { "type": "boolean" }, "would": { "type": "string", "enum": [ "post", "queue_for_approval", "be_refused" ] }, "policy": { "$ref": "#/components/schemas/Policy" }, "period": { "anyOf": [ { "$ref": "#/components/schemas/Period" }, { "type": "null" } ] }, "entry": { "anyOf": [ { "$ref": "#/components/schemas/JournalEntry" }, { "$ref": "#/components/schemas/NormalizedEntry" }, { "type": "null" } ] }, "proposal": { "$ref": "#/components/schemas/Proposal" }, "document": { "anyOf": [ { "$ref": "#/components/schemas/Document" }, { "$ref": "#/components/schemas/DocumentPreview" } ] }, "payment": { "$ref": "#/components/schemas/Payment" }, "bank_line": { "$ref": "#/components/schemas/BankLine" }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } } }, "required": [ "outcome" ] }, "AgingTotals": { "type": "object", "properties": { "current": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "d1_30": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "d31_60": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "d61_90": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "over_90": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "current", "d1_30", "d31_60", "d61_90", "over_90", "total" ] }, "AgingReport": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ar", "ap" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "buckets": { "type": "array", "items": { "type": "string" } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "totals": { "$ref": "#/components/schemas/AgingTotals" } }, "required": [ "contact_id", "contact_name", "totals" ] } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "invoice", "credit_memo", "bill", "vendor_credit", "sales_receipt", "refund", "vendor_refund", "expense", "check", "transfer", "payment" ], "description": "payment: the unapplied part of a payment" }, "number": { "type": "string" }, "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "days_overdue": { "type": "integer" }, "open_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Negative for an unapplied credit or payment" }, "bucket": { "type": "string", "enum": [ "current", "d1_30", "d31_60", "d61_90", "over_90" ] }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "The document's (or payment's) full amount" } }, "required": [ "id", "kind", "number", "contact_id", "due_date", "days_overdue", "open_cents", "bucket" ] } }, "totals": { "$ref": "#/components/schemas/AgingTotals" }, "control_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ties_out": { "type": "boolean", "description": "Aging total equals the AR/AP control account per the ledger, to the cent" } }, "required": [ "kind", "as_of", "contacts", "documents", "totals", "control_balance_cents", "ties_out" ] }, "Session": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "user_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "api_key_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "last_seen_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "idle_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "absolute_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoke_reason": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "current": { "type": "boolean" } }, "required": [ "id", "user_id", "created_at", "idle_expires_at", "absolute_expires_at", "revoked_at" ] }, "AuditActor": { "type": "object", "properties": { "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] }, "events": { "type": "integer" }, "last_seq": { "type": "integer" } }, "required": [ "actor_type", "actor_id", "name", "model", "events", "last_seq" ] }, "FiscalYearPeriods": { "type": "object", "properties": { "fiscal_year": { "type": "integer" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "created": { "type": "array", "items": { "$ref": "#/components/schemas/Period" } }, "periods": { "type": "array", "items": { "$ref": "#/components/schemas/Period" } } }, "required": [ "fiscal_year", "start_date", "end_date", "created", "periods" ] }, "QbwcStep": { "type": "object", "properties": { "id": { "type": "string", "description": "Plan step, e.g. list:AccountQuery, txn:InvoiceQuery:2025-03, report:TrialBalance:2025-03-31" }, "kind": { "type": "string", "enum": [ "meta", "list", "census", "txn", "recheck", "report" ] }, "status": { "type": "string", "enum": [ "pending", "done", "failed", "skipped" ] }, "records": { "type": "integer" }, "requests": { "type": "integer" }, "message": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "status", "records" ] }, "QbwcConnection": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "status": { "type": "string", "enum": [ "active", "locked", "revoked" ] }, "phase": { "type": "string", "enum": [ "meta", "lists", "census", "txns", "reports", "done" ] }, "percent": { "type": "integer", "minimum": 0, "maximum": 100 }, "sessions": { "type": "integer" }, "message": { "type": "string" }, "tieout": { "type": [ "string", "null" ], "enum": [ "PASS", "FAIL", null ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "include_tax_ids": { "type": "boolean" }, "download_used": { "type": "boolean" }, "download_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "failed_attempts": { "type": "integer" }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoke_reason": { "type": [ "string", "null" ] }, "qbwc_version": { "type": [ "string", "null" ] }, "qbxml_version": { "type": [ "string", "null" ] }, "started_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "finished_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/QbwcStep" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "status", "phase", "percent", "sessions", "message", "tieout", "created_at", "expires_at", "as_of", "download_used", "revoked_at" ] }, "QbwcBundle": { "type": "object", "properties": { "name": { "type": "string" }, "bundle_sha256": { "type": "string" }, "tieout_result": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "name", "bundle_sha256", "tieout_result" ] }, "Migration": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "source": { "type": "string", "enum": [ "qbd", "qbd-qbwc", "qbo" ] }, "connection_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "qbo_connection_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "bundle_sha256": { "type": "string" }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "status": { "type": "string", "enum": [ "imported", "failed" ] }, "result": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "report": { "type": [ "object", "null" ], "description": "The ledger's own tie-out (evenbead-import-tieout v1): per month-end trial balance vs QuickBooks, per-transaction checks against the General Ledger, AR/AP aging, counts" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "finished_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "cutover_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "cutover_by": { "type": [ "string", "null" ] } }, "required": [ "id", "source", "bundle_sha256", "as_of", "status", "result", "created_at", "cutover_at" ] }, "Firm": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "agent_writes_suspended": { "type": "boolean", "description": "Firm-wide kill switch: every firm agent's writes refused in every client" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "name", "agent_writes_suspended", "created_at" ] }, "FirmMember": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "role": { "type": "string", "enum": [ "admin", "cpa", "bookkeeper" ], "description": "admin and cpa: all scopes in clients (admin also manages the firm); bookkeeper: read and propose." }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "removed_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "remove_reason": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "role", "created_at", "removed_at" ] }, "FirmAgentAssignment": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "company_name": { "type": "string" }, "agent_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "The agent's identity inside that company" }, "active": { "type": "boolean" }, "posting_threshold_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "client_revoked": { "type": "boolean", "description": "The client revoked this agent in their company (final)" } }, "required": [ "company_id", "company_name", "agent_id", "active", "posting_threshold_cents", "scopes", "client_revoked" ] }, "FirmAgent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "created_by": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/FirmAgentAssignment" } } }, "required": [ "id", "name", "scopes", "created_at", "revoked_at" ] }, "FirmKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "key_prefix": { "type": "string" }, "principal_type": { "type": "string", "enum": [ "member", "agent" ] }, "member_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "firm_agent_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "last_used_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the firm default)." }, "rotated_from_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "rotated_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "status": { "type": "string", "enum": [ "active", "expired", "revoked" ] } }, "required": [ "id", "key_prefix", "principal_type", "scopes", "revoked_at", "expires_at", "last_used_at", "rate_limit_rpm", "status" ] }, "OwnerInviteIssued": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "token": { "type": [ "string", "null" ], "description": "The invitation (ebi_...), shown ONCE; hand it to the owner. null on an idempotent replay." }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "claim_path": { "type": "string", "description": "Where the owner claims it: the web page, or POST /v1/owner-invites/claim with the token as Bearer" } }, "required": [ "id", "token", "expires_at", "claim_path" ] }, "FirmGrant": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "company_name": { "type": "string" }, "firm_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "firm_name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "billing": { "type": "string", "enum": [ "firm", "client" ], "description": "Who pays for the company file (ADR-0009): firm-billed wholesale or client-billed. Recorded only." }, "granted_by_type": { "type": "string" }, "granted_by_id": { "type": "string" }, "granted_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "reason": { "type": [ "string", "null" ] }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoked_by_type": { "type": [ "string", "null" ] }, "revoked_by_id": { "type": [ "string", "null" ] }, "revoke_reason": { "type": [ "string", "null" ] }, "live": { "type": "boolean" } }, "required": [ "id", "company_id", "firm_id", "firm_name", "scopes", "billing", "granted_at", "revoked_at", "live" ] }, "FirmSession": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "member_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "last_seen_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "idle_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "absolute_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "revoke_reason": { "type": [ "string", "null" ] }, "current": { "type": "boolean" } }, "required": [ "id", "member_id", "created_at", "idle_expires_at", "absolute_expires_at", "revoked_at" ] }, "FirmMe": { "type": "object", "properties": { "firm": { "$ref": "#/components/schemas/Firm" }, "principal_type": { "type": "string", "enum": [ "member", "agent" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "role": { "type": [ "string", "null" ], "enum": [ "admin", "cpa", "bookkeeper" ], "description": "admin and cpa: all scopes in clients (admin also manages the firm); bookkeeper: read and propose." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "key_prefix": { "type": "string" }, "session": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "idle_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "absolute_expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id" ] }, "key": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "rate_limit_rpm": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000, "description": "This key's own rate budget in requests per minute (null: the firm default)." }, "rotated_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "expires_at" ] } }, "required": [ "firm", "principal_type", "id", "name", "role", "scopes", "key_prefix" ] }, "ClientStatus": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "company_name": { "type": "string" }, "grant_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "billing": { "type": "string", "enum": [ "firm", "client" ], "description": "Who pays for the company file (ADR-0009): firm-billed wholesale or client-billed. Recorded only." }, "grant_scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "granted_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "my_scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "description": "What the caller can do in this client (key ∩ role ∩ grant)" }, "agent_writes_suspended": { "type": "boolean" }, "bank": { "type": "object", "properties": { "accounts": { "type": "integer" }, "unmatched_lines": { "type": "integer" }, "unreconciled_accounts": { "type": "integer", "description": "Bank accounts with no finished reconciliation through reconciled_through" }, "reconciled_through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, "required": [ "accounts", "unmatched_lines", "unreconciled_accounts", "reconciled_through" ] }, "proposals": { "type": "object", "properties": { "pending": { "type": "integer" }, "oldest_pending_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "pending", "oldest_pending_at" ] }, "periods": { "type": "object", "properties": { "current_status": { "type": [ "string", "null" ], "enum": [ "open", "soft_locked", "hard_locked", null ], "description": "Status of the period containing as_of (null: no period)" }, "current_period": { "anyOf": [ { "type": "object", "properties": { "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." } }, "required": [ "start_date", "end_date" ] }, { "type": "null" } ] }, "hard_locked_through": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "soft_locked_through": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "open_before_as_of": { "type": "integer", "description": "Open periods that ended before as_of" } }, "required": [ "current_status", "current_period", "hard_locked_through", "soft_locked_through", "open_before_as_of" ] }, "overdue_ar": { "type": "object", "properties": { "invoices": { "type": "integer" }, "cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents." } }, "required": [ "invoices", "cents" ] }, "last_activity": { "anyOf": [ { "type": "object", "properties": { "at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "action": { "type": "string" } }, "required": [ "at", "action" ] }, { "type": "null" } ] }, "migration": { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "import" }, "status": { "type": "string" }, "result": { "type": [ "string", "null" ] }, "cutover_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "kind", "status" ] }, { "type": "object", "properties": { "kind": { "const": "qbwc" }, "status": { "type": "string" } }, "required": [ "kind", "status" ] }, { "type": "null" } ] }, "owner_invite": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "claimed", "expired", "revoked" ] }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "status", "expires_at" ] }, { "type": "null" } ], "description": "Clients the firm created: has the owner claimed the company (ADR-0023)? null when the client granted access itself." } }, "required": [ "company_id", "company_name", "billing", "grant_scopes", "my_scopes", "bank", "proposals", "periods", "overdue_ar", "last_activity", "migration" ] }, "IssuedFirmKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "key": { "type": [ "string", "null" ], "description": "The secret, shown ONCE. null on an idempotent replay." }, "key_prefix": { "type": "string" }, "principal_type": { "type": "string", "enum": [ "member", "agent" ] }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "minItems": 1, "maxItems": 4 }, "expires_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "key", "key_prefix", "principal_type", "scopes" ] }, "BulkLockResult": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "ok": { "type": "boolean" }, "period": { "$ref": "#/components/schemas/Period" }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "message" ] } }, "required": [ "company_id", "ok" ] }, "CloseItem": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "bank_reconciled", "proposals_cleared", "unapplied_payments", "aging_tied", "sales_tax_reviewed", "period_locked" ] }, "status": { "type": "string", "enum": [ "pass", "fail", "not_applicable" ] }, "summary": { "type": "string" }, "details": { "type": "object", "description": "The evidence: accounts and how far each is reconciled, waiting proposals, unapplied payments, aging vs control account, the liability by agency and the review, the period status." } }, "required": [ "key", "status", "summary", "details" ] }, "CloseSignoff": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "sales_tax_reviewed", "period_closed" ] }, "actor_id": { "type": "string" }, "actor_name": { "type": [ "string", "null" ] }, "snapshot": { "type": "object", "description": "What was attested: the liability by agency (review) or the checklist (close)" }, "note": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "kind", "actor_id", "snapshot", "created_at" ] }, "CloseChecklist": { "type": "object", "properties": { "period": { "$ref": "#/components/schemas/Period" }, "unapplied_days": { "type": "integer", "minimum": 0, "maximum": 3660 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CloseItem" } }, "passed": { "type": "integer", "description": "Items that pass or do not apply" }, "total": { "type": "integer" }, "ready_to_lock": { "type": "boolean", "description": "Every check before the lock passes (or does not apply)" }, "closed": { "type": "boolean", "description": "The period is locked and the close was recorded through the checklist" }, "sales_tax_review": { "anyOf": [ { "$ref": "#/components/schemas/CloseSignoff" }, { "type": "null" } ] }, "close": { "anyOf": [ { "$ref": "#/components/schemas/CloseSignoff" }, { "type": "null" } ] } }, "required": [ "period", "unapplied_days", "items", "passed", "total", "ready_to_lock", "closed", "sales_tax_review", "close" ] }, "ClientProposal": { "allOf": [ { "$ref": "#/components/schemas/Proposal" }, { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "company_name": { "type": "string" }, "firm_agent_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "age_days": { "type": "integer", "minimum": 0 }, "my_scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] }, "description": "What the caller can do in this client (key ∩ role ∩ grant): approve is needed to decide" } }, "required": [ "company_id", "company_name", "age_days", "my_scopes" ] } ] }, "ProposalDecisionResult": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "approved", "rejected", "would_approve", "would_reject", "refused" ] }, "journal_entry_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "proposal": { "$ref": "#/components/schemas/Proposal" }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "message" ] } }, "required": [ "company_id", "proposal_id", "ok", "status" ] }, "ClientCloseStatus": { "type": "object", "properties": { "company_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "company_name": { "type": "string" }, "my_scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "propose", "approve", "admin" ] } }, "checklist": { "anyOf": [ { "$ref": "#/components/schemas/CloseChecklist" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "message" ] }, { "type": "null" } ], "description": "Why no checklist (e.g. period_missing)" } }, "required": [ "company_id", "company_name", "my_scopes", "checklist", "error" ] }, "QboConnection": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "status": { "type": "string", "enum": [ "awaiting_authorization", "connected", "extracted", "failed", "revoked" ], "description": "failed: the extraction's tie-out did not pass (see last_run and the tie-out)" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "include_tax_ids": { "type": "boolean" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601." }, "authorized": { "type": "boolean", "description": "Intuit consent completed for one QuickBooks company (recorded once)" }, "authorized_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "authorization_expires_at": { "type": "string", "description": "The consent link (state) works once, until then" }, "estimate": { "type": [ "object", "null" ], "description": "The last pre-flight call estimate" }, "last_run": { "type": [ "object", "null" ], "description": "The last extraction: calls made, estimate, token rotations, tie-out result, record counts" }, "revoked_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "revoke_reason": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "environment", "as_of", "created_at", "authorized", "estimate", "last_run", "revoked_at" ] }, "QboBundle": { "type": "object", "properties": { "name": { "type": "string" }, "bundle_sha256": { "type": "string" }, "tieout_result": { "type": "string", "enum": [ "PASS", "FAIL" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601." } }, "required": [ "name", "bundle_sha256", "tieout_result" ] }, "QboCallEstimate": { "type": "object", "properties": { "total": { "type": "integer", "description": "Metered reads the extraction will make (retries excluded)" }, "breakdown": { "type": "object", "properties": { "company": { "type": "integer" }, "counts": { "type": "integer" }, "list_pages": { "type": "integer" }, "txn_pages": { "type": "integer" }, "reports": { "type": "integer" } } }, "records": { "type": "object", "description": "COUNT per QuickBooks Online entity" }, "months": { "type": "integer" } }, "required": [ "total", "breakdown", "records", "months" ] }, "QboUsage": { "type": "object", "properties": { "environment": { "type": "string" }, "month": { "type": "string" }, "used": { "type": "integer" }, "budget": { "type": "integer" }, "remaining": { "type": "integer" } }, "required": [ "environment", "month", "used", "budget", "remaining" ] }, "Email": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string", "enum": [ "invoice", "credit_memo", "sales_receipt", "estimate", "payment_reminder", "security_new_key", "security_firm_granted", "security_firm_revoked" ] }, "to_address": { "type": "string" }, "to_name": { "type": [ "string", "null" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "from_name": { "type": "string" }, "reply_to": { "type": [ "string", "null" ] }, "subject": { "type": "string" }, "attachment_name": { "type": [ "string", "null" ] }, "document_id": { "type": [ "string", "null" ] }, "estimate_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending_approval", "queued", "sending", "sent", "failed", "suppressed", "rejected", "cancelled" ] }, "policy": { "type": [ "object", "null" ], "description": "Why an agent's email waits for approval: reasons over_threshold, new_recipient, first_email." }, "requested_by_type": { "type": "string" }, "requested_by_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "decided_by_type": { "type": [ "string", "null" ] }, "decided_by_id": { "type": [ "string", "null" ] }, "decided_at": { "type": [ "string", "null" ], "description": "UTC timestamp (ISO 8601) or null." }, "decision_reason": { "type": [ "string", "null" ] }, "attempts": { "type": "integer" }, "next_attempt_at": { "type": [ "string", "null" ], "description": "UTC timestamp (ISO 8601) or null." }, "last_attempt_at": { "type": [ "string", "null" ], "description": "UTC timestamp (ISO 8601) or null." }, "last_error": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string" }, "sent_at": { "type": [ "string", "null" ], "description": "UTC timestamp (ISO 8601) or null." } }, "required": [ "id", "kind", "to_address", "status", "created_at" ] }, "EmailSendRequest": { "type": "object", "properties": { "to": { "type": "string", "maxLength": 254, "pattern": "^[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+@[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+\\.[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+$", "description": "Recipient (default: the customer's email on file). Anything else makes an agent's send a proposal." }, "to_name": { "type": "string", "maxLength": 200, "pattern": "^[^\\r\\n]*$" }, "cc": { "type": "array", "items": { "type": "string", "maxLength": 254, "pattern": "^[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+@[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+\\.[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+$", "description": "An email address." }, "maxItems": 5 }, "message": { "type": "string", "maxLength": 2000, "description": "A short note shown above the document details." }, "dry_run": { "type": "boolean", "description": "Preview the recipients, subject, attachment and policy verdict without queuing." } }, "additionalProperties": false }, "EmailSettings": { "type": "object", "properties": { "reply_to": { "type": [ "string", "null" ], "maxLength": 254, "pattern": "^[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+@[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+\\.[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+$", "description": "An email address." }, "display_name": { "type": [ "string", "null" ] }, "security_notices_to": { "type": [ "string", "null" ], "maxLength": 254, "pattern": "^[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+@[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+\\.[^\\s<>()\\r\\n,;:\"\\\\\\[\\]]+$", "description": "An email address." }, "reminders_enabled": { "type": "boolean" }, "reminder_days": { "type": "array", "items": { "type": "integer" } }, "email_available": { "type": "boolean" }, "reminders_available": { "type": "boolean" }, "sender": { "type": "string", "description": "The From line customers see: your display name (or company name) ." } }, "required": [ "reply_to", "display_name", "security_notices_to", "reminders_enabled", "reminder_days", "email_available", "reminders_available", "sender" ] }, "EmailSuppression": { "type": "object", "properties": { "address": { "type": "string" }, "scope": { "type": "string", "enum": [ "all", "reminders", "marketing" ] }, "reason": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "address", "scope", "reason", "created_at" ] }, "BankFeedAccount": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "account_id": { "type": "string", "description": "Plaid's account id (opaque)" }, "name": { "type": "string" }, "official_name": { "type": [ "string", "null" ] }, "mask": { "type": [ "string", "null" ], "description": "Last digits only" }, "type": { "type": "string", "description": "depository or credit are importable" }, "subtype": { "type": [ "string", "null" ] }, "bank_account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "bank_account_name": { "type": [ "string", "null" ] }, "import_from": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Lines dated before this are not imported (file history is not duplicated)" }, "mapped_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." } }, "required": [ "id", "account_id", "name", "type", "bank_account_id", "import_from" ] }, "BankFeed": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "institution_id": { "type": [ "string", "null" ] }, "institution_name": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "login_required", "pending_expiration", "revoked", "error", "removed" ], "description": "login_required / pending_expiration: reconnect (Link update mode); revoked: the person revoked access at the bank; removed: disconnected (final)" }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "consent_expires_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "new_accounts_available": { "type": "boolean" }, "include_pending": { "type": "boolean", "description": "Import pending transactions too (default false: posted only)" }, "sync_requested_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "last_synced_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "last_sync": { "type": [ "object", "null" ], "description": "The last sync's summary" }, "last_webhook_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601." }, "removed_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601." }, "removed_reason": { "type": [ "string", "null" ] }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/BankFeedAccount" } } }, "required": [ "id", "environment", "status", "include_pending", "last_synced_at", "created_at", "accounts" ] }, "BankFeedSync": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "synced", "busy", "login_required", "error", "no_linked_accounts" ], "description": "busy: another sync of this feed is running" }, "pages": { "type": "integer" }, "restarts": { "type": "integer" }, "update_status": { "type": [ "string", "null" ] }, "counts": { "anyOf": [ { "type": "object", "properties": { "added": { "type": "integer" }, "modified": { "type": "integer" }, "removed": { "type": "integer" }, "imported": { "type": "integer", "description": "New bank lines" }, "deduped": { "type": "integer", "description": "Already imported from a file (same amount within 3 days): not imported again" }, "excluded": { "type": "integer", "description": "Unmatched lines excluded because the bank removed or replaced them" }, "conflicts": { "type": "integer", "description": "Changed or removed at the bank after the line was matched or categorized: left for a person" }, "pending_ignored": { "type": "integer" }, "unmapped": { "type": "integer", "description": "Transactions of accounts not linked to a bank account" }, "before_cutoff": { "type": "integer", "description": "Dated before the account's import_from date" }, "unchanged": { "type": "integer" }, "skipped": { "type": "integer" } } }, { "type": "null" } ] }, "conflicts": { "type": "array", "items": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "bank_line_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "reason": { "type": "string" } } } }, "lines_imported": { "type": "array", "items": { "type": "object", "properties": { "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "import_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "lines_new": { "type": "integer" } } } }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, { "type": "null" } ] } }, "required": [ "status", "counts", "conflicts", "lines_imported", "error" ] }, "Estimate": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "number": { "type": "string" }, "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "estimate_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "expiry_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "reference": { "type": [ "string", "null" ] }, "memo": { "type": "string" }, "tax_rate_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "tax_rate_name": { "type": [ "string", "null" ] }, "tax_rate_ppm": { "type": [ "integer", "null" ] }, "subtotal_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "tax_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "status": { "type": "string", "enum": [ "open", "accepted", "declined", "converted", "void" ] }, "status_reason": { "type": [ "string", "null" ] }, "status_changed_at": { "type": [ "string", "null" ], "description": "UTC timestamp, ISO 8601 with microseconds." }, "converted_document_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "converted_document_number": { "type": [ "string", "null" ] }, "expired": { "type": "boolean", "description": "Open or accepted and past its expiry date" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." }, "lines": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentLine" } } }, "required": [ "id", "number", "contact_id", "contact_name", "estimate_date", "subtotal_cents", "tax_cents", "total_cents", "status", "expired" ] }, "TaxAgency": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } }, "required": [ "id", "name", "active" ] }, "TaxRateComponent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "agency_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agency_name": { "type": "string" }, "rate_ppm": { "type": "integer" }, "rate_text": { "type": "string" }, "payable_account_code": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "name", "agency_id", "agency_name", "rate_ppm", "rate_text", "payable_account_code", "active" ] }, "TaxRate": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "agency_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "description": "null for a combined rate" }, "agency_name": { "type": [ "string", "null" ] }, "rate_ppm": { "type": "integer", "minimum": 0, "maximum": 1000000, "description": "Parts per million (9.75% = 97500); a combined rate: the sum of its components" }, "rate_text": { "type": "string" }, "payable_account_code": { "type": [ "string", "null" ] }, "payable_account_name": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "combined": { "type": "boolean", "description": "Made of several single-agency rates (state + county + city), each posting to its own payable account" }, "components": { "type": "array", "items": { "$ref": "#/components/schemas/TaxRateComponent" }, "description": "The jurisdictions: a single rate is its own one component" } }, "required": [ "id", "name", "agency_id", "rate_ppm", "rate_text", "payable_account_code", "active", "combined", "components" ] }, "SalesTaxReport": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "basis": { "const": "accrual" }, "group_by": { "type": "string", "enum": [ "month", "quarter" ] }, "rates": { "type": "array", "items": { "type": "object", "properties": { "rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "rate_name": { "type": "string" }, "rate_ppm": { "type": "integer" }, "rate_text": { "type": "string" }, "combined": { "type": "boolean" }, "agency_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agency_name": { "type": [ "string", "null" ] }, "payable_account_code": { "type": [ "string", "null" ] }, "taxable_sales_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "non_taxable_sales_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "documents": { "type": "integer" } }, "required": [ "rate_id", "rate_name", "agency_name", "taxable_sales_cents", "non_taxable_sales_cents", "tax_cents" ] }, "description": "Per rate named on documents (a combined rate once, with its total)" }, "components": { "type": "array", "items": { "type": "object", "properties": { "rate_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "rate_name": { "type": "string" }, "rate_ppm": { "type": "integer" }, "rate_text": { "type": "string" }, "agency_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agency_name": { "type": "string" }, "payable_account_code": { "type": "string" }, "taxable_sales_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "documents": { "type": "integer" } }, "required": [ "rate_id", "rate_name", "agency_id", "agency_name", "payable_account_code", "taxable_sales_cents", "tax_cents" ] }, "description": "Per jurisdiction (single-agency rate), from the tax lines" }, "untaxed": { "type": "object", "properties": { "sales_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "documents": { "type": "integer" } }, "required": [ "sales_cents", "documents" ] }, "agencies": { "type": "array", "items": { "type": "object", "properties": { "agency_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agency_name": { "type": "string" }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "payable_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "payable_accounts": { "type": "array", "items": { "type": "string" } }, "ledger_tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ties_out": { "type": "boolean", "description": "This agency's tax equals the ledger's movement on its payable account(s) from these documents" } }, "required": [ "agency_id", "agency_name", "tax_cents", "payable_balance_cents", "ledger_tax_cents", "ties_out" ] } }, "periods": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "end": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "label": { "type": "string" }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "agencies": { "type": "array", "items": { "type": "object", "properties": { "agency_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "agency_name": { "type": "string" }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "agency_id", "agency_name", "tax_cents" ] } } }, "required": [ "start", "end", "label", "agencies", "tax_cents" ] }, "description": "Tax per agency for each month or quarter inside the range (issues on their date, voids on theirs)" }, "totals": { "type": "object", "properties": { "taxable_sales_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "non_taxable_sales_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "taxable_sales_cents", "non_taxable_sales_cents", "tax_cents" ] }, "ledger_tax_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ties_out": { "type": "boolean", "description": "The report's tax equals the ledger's net movement on the payable accounts from those documents" } }, "required": [ "from", "to", "group_by", "rates", "components", "untaxed", "agencies", "periods", "totals", "ledger_tax_cents", "ties_out" ] }, "RecurringRun": { "type": "object", "properties": { "occurrence_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "outcome": { "type": "string", "enum": [ "posted", "pending_approval" ] }, "document_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "document_number": { "type": [ "string", "null" ] }, "proposal_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "occurrence_date", "outcome", "document_id", "proposal_id" ] }, "RecurringTemplate": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "invoice", "bill" ] }, "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "frequency": { "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ] }, "interval_count": { "type": "integer" }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "end_date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "request": { "type": "object" }, "active": { "type": "boolean" }, "total_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "next_occurrence": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "runs_count": { "type": "integer" }, "last_run": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "name", "kind", "contact_id", "frequency", "interval_count", "start_date", "end_date", "active", "next_occurrence" ] }, "RecurringOccurrence": { "type": "object", "properties": { "occurrence_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "outcome": { "type": "string", "enum": [ "posted", "pending_approval", "refused" ] }, "document": { "anyOf": [ { "$ref": "#/components/schemas/Document" }, { "$ref": "#/components/schemas/DocumentPreview" } ] }, "proposal": { "$ref": "#/components/schemas/Proposal" }, "error": { "type": "object", "properties": { "type": { "type": "string" }, "message": { "type": "string" }, "validation_errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationIssue" } } }, "required": [ "type", "message" ] } }, "required": [ "occurrence_date", "outcome" ] }, "RecurringRunResult": { "type": "object", "properties": { "template_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "through": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "dry_run": { "type": "boolean" }, "occurrences": { "type": "array", "items": { "$ref": "#/components/schemas/RecurringOccurrence" } }, "next_occurrence": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "more_due": { "type": "boolean", "description": "More occurrences are due than one run generates (36); run again" } }, "required": [ "template_id", "through", "dry_run", "occurrences", "next_occurrence" ] }, "PdfFile": { "type": "object", "properties": { "filename": { "type": "string" }, "content_type": { "const": "application/pdf" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "pdf_base64": { "type": "string" } }, "required": [ "filename", "content_type", "bytes", "sha256", "pdf_base64" ] }, "Attachment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "file_name": { "type": "string" }, "content_type": { "type": "string" }, "size_bytes": { "type": "integer" }, "sha256": { "type": [ "string", "null" ] }, "note": { "type": "string" }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "created_at": { "type": "string", "description": "UTC timestamp, ISO 8601 with microseconds." } }, "required": [ "id", "file_name", "content_type", "size_bytes", "sha256", "created_at" ] }, "AccountRegister": { "type": "object", "properties": { "account": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "name": { "type": "string" }, "type": { "type": "string" }, "subtype": { "type": [ "string", "null" ] }, "control": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "bank_account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "code", "name", "type" ] }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "opening_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "closing_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "total_debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "total_credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "lines": { "type": "array", "items": { "type": "object", "properties": { "journal_line_id": { "type": "integer" }, "entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entry_no": { "type": "integer" }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string" }, "line_memo": { "type": "string" }, "class": { "type": [ "string", "null" ] }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "payment", "entry" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "label": { "type": "string" }, "number": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": [ "string", "null" ] }, "void": { "type": "boolean", "description": "This entry voids the document or payment" } }, "required": [ "type", "id", "kind", "label", "number", "void" ] }, "other_accounts": { "type": "string", "description": "The other accounts of the entry (the split)" }, "debit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "credit_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Change in the account's natural balance (+ raises a bank balance or an amount owed on a card)" }, "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "reconciled": { "type": "boolean", "description": "Cleared by a finished reconciliation" } }, "required": [ "journal_line_id", "entry_id", "entry_no", "entry_date", "source", "debit_cents", "credit_cents", "amount_cents", "balance_cents", "reconciled" ] } }, "truncated": { "type": "boolean", "description": "More lines than limit; narrow the dates" } }, "required": [ "account", "from", "to", "opening_balance_cents", "closing_balance_cents", "lines", "truncated" ] }, "SalesOrExpensesByParty": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "basis": { "const": "accrual" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "documents": { "type": "integer" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "contact_id", "contact_name", "documents", "amount_cents" ] } }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ledger_total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The P&L's total for the same accounts and range" }, "unattributed_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "In the P&L but on no customer/vendor document (journal entries, bank categorizations)" } }, "required": [ "from", "to", "rows", "total_cents", "ledger_total_cents", "unattributed_cents" ] }, "SalesByItem": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "basis": { "const": "accrual" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "item_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "item_name": { "type": "string" }, "quantity": { "type": "string", "description": "Exact decimal" }, "lines": { "type": "integer" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "average_price_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "item_id", "item_name", "quantity", "lines", "amount_cents" ] } }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "from", "to", "rows", "total_cents" ] }, "OpenDocuments": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ar", "ap" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": "string" }, "open_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "overdue_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "number": { "type": "string" }, "doc_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "days_overdue": { "type": "integer" }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "open_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "bucket": { "type": "string" } }, "required": [ "id", "kind", "number", "due_date", "days_overdue", "open_cents" ] } } }, "required": [ "contact_id", "contact_name", "open_cents", "documents" ] } }, "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "overdue_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "control_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "ties_out": { "type": "boolean" } }, "required": [ "kind", "as_of", "contacts", "total_cents", "control_balance_cents", "ties_out" ] }, "TransactionList": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "rows": { "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "entry_no": { "type": "integer" }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "memo": { "type": "string" }, "source": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "payment", "entry" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "label": { "type": "string" }, "number": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "contact_name": { "type": [ "string", "null" ] }, "void": { "type": "boolean", "description": "This entry voids the document or payment" } }, "required": [ "type", "id", "kind", "label", "number", "void" ] }, "accounts": { "type": "string" }, "amount_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "actor_type": { "type": "string" }, "actor_id": { "type": "string" }, "model": { "type": [ "string", "null" ] } }, "required": [ "entry_id", "entry_no", "entry_date", "source", "amount_cents" ] } }, "total_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "truncated": { "type": "boolean" } }, "required": [ "from", "to", "rows", "total_cents", "truncated" ] }, "Summary1099": { "type": "object", "properties": { "year": { "type": "integer" }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "threshold_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Filing threshold used: $600 for payments through 2025, $2,000 after 2025-12-31 (indexed from 2027: pass threshold_cents)" }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "is_1099": { "type": "boolean" }, "tax_id_on_file": { "type": "boolean" }, "tax_id_last4": { "type": [ "string", "null" ] }, "paid_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Bill payments, expenses and checks to the vendor in the calendar year" }, "card_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Of which paid by card (reported by the card processor on a 1099-K)" }, "refunds_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Vendor refunds received in the year" }, "reportable_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "paid − card − refunds" }, "meets_threshold": { "type": "boolean" } }, "required": [ "contact_id", "name", "is_1099", "tax_id_on_file", "paid_cents", "card_cents", "refunds_cents", "reportable_cents", "meets_threshold" ] }, "description": "Vendors flagged for 1099s" }, "review": { "type": "array", "items": { "type": "object", "properties": { "contact_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "is_1099": { "type": "boolean" }, "tax_id_on_file": { "type": "boolean" }, "tax_id_last4": { "type": [ "string", "null" ] }, "paid_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Bill payments, expenses and checks to the vendor in the calendar year" }, "card_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Of which paid by card (reported by the card processor on a 1099-K)" }, "refunds_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Vendor refunds received in the year" }, "reportable_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "paid − card − refunds" }, "meets_threshold": { "type": "boolean" } }, "required": [ "contact_id", "name", "is_1099", "tax_id_on_file", "paid_cents", "card_cents", "refunds_cents", "reportable_cents", "meets_threshold" ] }, "description": "Vendors not flagged whose reportable payments reach the threshold" }, "total_reportable_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." }, "forms_needed": { "type": "integer" }, "missing_tax_ids": { "type": "integer" } }, "required": [ "year", "threshold_cents", "vendors", "review", "total_reportable_cents", "forms_needed", "missing_tax_ids" ] }, "Dashboard": { "type": "object", "properties": { "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "month": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "income_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "expenses_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "net_income_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "from", "to", "income_cents", "expenses_cents", "net_income_cents" ] }, "year_to_date": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "income_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "expenses_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "net_income_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "from", "to", "income_cents", "expenses_cents", "net_income_cents" ] }, "cash": { "type": "object", "properties": { "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "name": { "type": "string" }, "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "code", "name", "balance_cents" ] } }, "trend": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "string" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." } }, "required": [ "month", "date", "balance_cents" ] }, "description": "Cash at each of the last 12 month-ends (the last point is as_of)" } }, "required": [ "balance_cents", "accounts", "trend" ] }, "ar": { "type": "object", "properties": { "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "overdue_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "total_cents", "overdue_cents" ] }, "ap": { "type": "object", "properties": { "total_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "overdue_cents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Integer cents (100 = $1.00). Never a float." } }, "required": [ "total_cents", "overdue_cents" ] }, "reconcile": { "type": "array", "items": { "type": "object", "properties": { "bank_account_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "name": { "type": "string" }, "ledger_account_code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$" }, "kind": { "type": "string" }, "last_reconciled": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "uncleared_lines": { "type": "integer" }, "oldest_uncleared": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "open_reconciliation_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } }, "required": [ "bank_account_id", "name", "uncleared_lines" ] }, "description": "Bank and card accounts with ledger lines no finished reconciliation has cleared, oldest first" } }, "required": [ "as_of", "month", "year_to_date", "cash", "ar", "ap", "reconcile" ] }, "SearchResult": { "type": "object", "properties": { "query": { "type": "string" }, "amount_cents": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991, "description": "The query read as an amount, when it is one" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "payment", "entry", "contact", "item", "account" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "amount_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Accounts: the code (registers are addressed by it)" } }, "required": [ "type", "id", "kind", "title", "subtitle", "date", "amount_cents" ] } }, "contacts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "payment", "entry", "contact", "item", "account" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "amount_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Accounts: the code (registers are addressed by it)" } }, "required": [ "type", "id", "kind", "title", "subtitle", "date", "amount_cents" ] } }, "items": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "payment", "entry", "contact", "item", "account" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "amount_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Accounts: the code (registers are addressed by it)" } }, "required": [ "type", "id", "kind", "title", "subtitle", "date", "amount_cents" ] } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "payment", "entry", "contact", "item", "account" ] }, "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "kind": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "date": { "type": [ "string", "null" ], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Calendar date, YYYY-MM-DD." }, "amount_cents": { "type": [ "integer", "null" ], "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Signed integer cents." }, "code": { "type": "string", "pattern": "^[0-9A-Za-z][0-9A-Za-z.-]{0,19}$", "description": "Accounts: the code (registers are addressed by it)" } }, "required": [ "type", "id", "kind", "title", "subtitle", "date", "amount_cents" ] } } }, "required": [ "query", "amount_cents", "transactions", "contacts", "items", "accounts" ] } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Per-principal API key (eb_...). Scopes: read, propose, approve, admin. Accounting firms use firm keys (eb_...) or firm sessions (ebf_...): directly on /v1/firm operations, and on any company operation with the X-Evenbead-Company header (the client must have granted the firm access). Keys expire (people: 365 days; agents: 30 days by default, at most 90) and rotate with an overlap window (POST /v1/keys/{id}/rotate). Requests are rate-limited per key, per company (agents) and per address: 429 with Retry-After." }, "ownerInvite": { "type": "http", "scheme": "bearer", "description": "A company owner's single-use invitation (ebi_...), issued to the firm that created the company and handed to the owner; only for claiming the owner key." }, "bootstrap": { "type": "http", "scheme": "bearer", "description": "Operator bootstrap token (EVENBEAD_BOOTSTRAP_TOKEN), only for creating companies." } } } }