{ "openapi": "3.1.0", "info": { "title": "Vision Accounting API", "version": "0.1.1", "description": "Provider-neutral Accounting domain API. Live provider, tax, posting, customer-data promotion, and production capabilities remain separately gated." }, "security": [ { "visionBearer": [] } ], "paths": { "/meta": { "get": { "operationId": "getAccountingMetadata", "security": [], "responses": { "200": { "description": "Contract metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metadata" } } } } } } }, "/ready": { "get": { "operationId": "getAccountingReadiness", "x-required-scope": "accounting:health:read", "responses": { "200": { "description": "Ready" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/actor": { "get": { "operationId": "getAccountingActor", "x-required-scope": "accounting:actor:read", "responses": { "200": { "description": "Effective Accounting actor" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/overview": { "get": { "operationId": "getAccountingOverview", "x-required-scope": "accounting:overview:read", "responses": { "200": { "description": "Accounting attention summary" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/counterparties": { "get": { "operationId": "listFinancialCounterparties", "x-required-scope": "accounting:counterparties:read", "responses": { "200": { "description": "Counterparty page" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createFinancialCounterparty", "x-required-scope": "accounting:counterparties:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CounterpartyCreate" } } } }, "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/counterparties/{reference}": { "get": { "operationId": "getFinancialCounterparty", "x-required-scope": "accounting:counterparties:read", "parameters": [ { "$ref": "#/components/parameters/CounterpartyReference" } ], "responses": { "200": { "description": "Counterparty detail" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/invoices": { "get": { "operationId": "listInvoices", "x-required-scope": "accounting:invoices:read", "responses": { "200": { "description": "Invoice page" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/invoices/{reference}": { "get": { "operationId": "getInvoice", "x-required-scope": "accounting:invoices:read", "parameters": [ { "$ref": "#/components/parameters/InvoiceReference" } ], "responses": { "200": { "description": "Invoice detail" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/invoice-drafts": { "post": { "operationId": "createInvoiceDraft", "x-required-scope": "accounting:invoices:draft", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftCreate" } } } }, "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/invoice-drafts/{reference}": { "put": { "operationId": "updateInvoiceDraft", "x-required-scope": "accounting:invoices:draft", "parameters": [ { "$ref": "#/components/parameters/InvoiceReference" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDraftUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/approval-intents": { "post": { "operationId": "prepareInvoiceApprovalIntent", "x-required-scope": "accounting:approvals:prepare", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/settings": { "get": { "operationId": "getAccountingSettings", "x-required-scope": "accounting:settings:read", "responses": { "200": { "description": "Workspace Accounting settings" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } }, "put": { "operationId": "updateAccountingSettings", "x-required-scope": "accounting:settings:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsUpdate" } } } }, "responses": { "200": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/provider-connections": { "get": { "operationId": "listProviderConnections", "x-required-scope": "accounting:providers:read", "responses": { "200": { "description": "Provider connection page without secrets" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } }, "/provider-connections/stripe": { "post": { "operationId": "connectStripeRestrictedKey", "x-required-scope": "accounting:providers:connect", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeConnection" } } } }, "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/import-runs": { "get": { "operationId": "listImportRuns", "x-required-scope": "accounting:imports:read", "responses": { "200": { "description": "Import run page" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createImportRun", "x-required-scope": "accounting:imports:create", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRunCreate" } } } }, "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/import-runs/{reference}": { "get": { "operationId": "getImportRun", "x-required-scope": "accounting:imports:read", "parameters": [ { "$ref": "#/components/parameters/ImportReference" } ], "responses": { "200": { "description": "Import run detail" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/import-runs/{reference}/artifacts": { "post": { "operationId": "registerImportArtifact", "x-required-scope": "accounting:imports:upload", "parameters": [ { "$ref": "#/components/parameters/ImportReference" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactRegister" } } } }, "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/import-runs/{reference}/mapping-set": { "put": { "operationId": "setImportMapping", "x-required-scope": "accounting:imports:map", "parameters": [ { "$ref": "#/components/parameters/ImportReference" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } }, "/import-runs/{reference}/candidate-revisions": { "post": { "operationId": "createImportCandidateRevision", "x-required-scope": "accounting:imports:validate", "parameters": [ { "$ref": "#/components/parameters/ImportReference" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "$ref": "#/components/responses/CommandResult" }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" } } } }, "/mcp-capabilities": { "get": { "operationId": "getAccountingMcpCapabilities", "x-required-scope": "accounting:imports:read", "responses": { "200": { "description": "Proposal-only MCP capability inventory" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "visionBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Vision-issued access token (JWT). Obtain via the token endpoint of the identity provider configured for this installation. Accounting accepts the Vision service-credential profile." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 16, "maxLength": 160, "pattern": "^[A-Za-z0-9._:-]+$" } }, "CounterpartyReference": { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^FCP-[A-Z0-9]{12}$" } }, "InvoiceReference": { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^INV-[A-Z0-9]{12}$" } }, "ImportReference": { "name": "reference", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^IMR-[A-Z0-9]{12}$" } } }, "responses": { "Error": { "description": "Safe Accounting error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "CommandResult": { "description": "Durable Accounting command result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommandResult" } } } } }, "schemas": { "Metadata": { "type": "object", "required": [ "schemaVersion", "service", "version", "status", "openapiPath" ], "properties": { "schemaVersion": { "const": "vision-accounting-api.v1" }, "service": { "const": "vision-accounting" }, "version": { "type": "string" }, "status": { "type": "string" }, "openapiPath": { "type": "string" } } }, "Money": { "type": "object", "additionalProperties": false, "required": [ "currency", "minorUnits", "scale" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "minorUnits": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, "scale": { "type": "integer", "minimum": 0, "maximum": 6 } } }, "CounterpartyCreate": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "displayName", "legalName", "role" ], "properties": { "schemaVersion": { "const": "vision-accounting-counterparty-create.v1" }, "displayName": { "type": "string", "minLength": 1, "maxLength": 240 }, "legalName": { "type": "string", "minLength": 1, "maxLength": 240 }, "role": { "enum": [ "customer", "vendor", "both" ] }, "defaultCurrency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$" }, "paymentTermsDays": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 365 }, "references": { "type": "array", "maxItems": 20 } } }, "InvoiceDraftCreate": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "counterpartyReference", "taxAmount", "lines" ], "properties": { "schemaVersion": { "const": "vision-accounting-invoice-draft-create.v1" }, "counterpartyReference": { "type": "string", "pattern": "^FCP-[A-Z0-9]{12}$" }, "billingProfileReference": { "type": [ "string", "null" ] }, "documentDate": { "type": [ "string", "null" ], "format": "date" }, "dueDate": { "type": [ "string", "null" ], "format": "date" }, "customerNote": { "type": [ "string", "null" ] }, "internalNote": { "type": [ "string", "null" ] }, "taxAmount": { "$ref": "#/components/schemas/Money" }, "lines": { "type": "array", "minItems": 1, "maxItems": 200 } } }, "InvoiceDraftUpdate": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "expectedInvoiceVersion", "counterpartyReference", "taxAmount", "lines" ], "properties": { "schemaVersion": { "const": "vision-accounting-invoice-draft-update.v1" }, "expectedInvoiceVersion": { "type": "integer", "minimum": 1 }, "counterpartyReference": { "type": "string", "pattern": "^FCP-[A-Z0-9]{12}$" }, "billingProfileReference": { "type": [ "string", "null" ] }, "documentDate": { "type": [ "string", "null" ], "format": "date" }, "dueDate": { "type": [ "string", "null" ], "format": "date" }, "customerNote": { "type": [ "string", "null" ] }, "internalNote": { "type": [ "string", "null" ] }, "taxAmount": { "$ref": "#/components/schemas/Money" }, "lines": { "type": "array", "minItems": 1, "maxItems": 200 } } }, "SettingsUpdate": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "expectedVersion", "legalName", "tradingName", "issuerAddress", "accountingBasis", "functionalCurrency", "fiscalYearStartMonth", "defaultPaymentTermsDays", "invoicePrefix" ], "properties": { "schemaVersion": { "const": "vision-accounting-settings-update.v1" }, "expectedVersion": { "type": "integer", "minimum": 1 }, "legalName": { "type": [ "string", "null" ], "maxLength": 240 }, "tradingName": { "type": [ "string", "null" ], "maxLength": 240 }, "issuerAddress": { "type": "object" }, "accountingBasis": { "enum": [ "undecided", "cash", "accrual" ] }, "functionalCurrency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "fiscalYearStartMonth": { "type": "integer", "minimum": 1, "maximum": 12 }, "defaultPaymentTermsDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "invoicePrefix": { "type": "string", "pattern": "^[A-Z0-9-]{1,20}$" } } }, "StripeConnection": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "mode", "restrictedApiKey" ], "properties": { "schemaVersion": { "const": "vision-accounting-stripe-connect.v1" }, "mode": { "enum": [ "test", "live" ] }, "restrictedApiKey": { "type": "string", "writeOnly": true, "pattern": "^rk_(test|live)_[A-Za-z0-9]{16,}$" } } }, "ImportRunCreate": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "adapterId", "adapterContractVersion", "adapterImplementationVersion", "sourceApplication", "mode", "intendedCoverage" ], "properties": { "schemaVersion": { "const": "vision-accounting-import-create.v1" }, "adapterId": { "type": "string" }, "adapterContractVersion": { "const": "vision-accounting-adapter.v1" }, "adapterImplementationVersion": { "type": "string" }, "sourceApplication": { "type": "object" }, "mode": { "enum": [ "opening_balances", "summary_history", "full_history", "evidence_only" ] }, "intendedCoverage": { "type": "object" } } }, "ArtifactRegister": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "fileName", "mediaType", "byteLength", "sha256", "objectReference", "scanState" ], "properties": { "schemaVersion": { "const": "vision-accounting-source-artifact-register.v1" }, "fileName": { "type": "string" }, "mediaType": { "enum": [ "application/zip", "application/json", "application/x-ndjson", "text/csv" ] }, "byteLength": { "type": "integer", "minimum": 0, "maximum": 536870912 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "objectReference": { "type": "string" }, "scanState": { "enum": [ "passed", "rejected", "unavailable" ] } } }, "CommandResult": { "type": "object", "required": [ "schemaVersion", "operation", "outcome", "commandReceiptReference", "subjectReference", "recordVersion", "replayed" ], "properties": { "schemaVersion": { "const": "vision-accounting-command-result.v1" }, "operation": { "type": "string" }, "outcome": { "enum": [ "succeeded", "pending" ] }, "commandReceiptReference": { "type": "string" }, "subjectReference": { "type": "string" }, "recordVersion": { "type": "integer", "minimum": 1 }, "replayed": { "type": "boolean" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "schemaVersion", "code", "message", "requestId", "retryable", "fieldIssues", "details" ], "properties": { "schemaVersion": { "const": "vision-accounting-error.v1" }, "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean" }, "fieldIssues": { "type": "array" }, "details": { "type": "object" } } } } } } } }