{ "openapi": "3.1.0", "info": { "title": "Haddon", "description": "Haddon: an open-source double-entry ledger for AI agents. It comes with an optional web interface for people.\nOne database file is one entity; every path below `/v1/entities/{entity_id}` is resolved inside that\nfile, so an id that exists for another entity is simply not found here.\n\n**Amounts** cross the wire as base-10 integer strings of micro-units (millionths), in both directions.\n`\"amount_micros\": \"-12000000\"` is -12.00 of a two-decimal commodity. JSON numbers are refused.\n\n**Dates** are inclusive `from`/`to` over one continuous journal. Either bound may be omitted (`from` means \"from\nthe beginning\", `to` means \"through the latest posting\"), and any valid range is accepted; `trial-balance` and\n`balance-sheet` take a point `as_of` instead. A range that merely ends in the future is fine; one that has not\nbegun is refused.\n\n**Pagination** returns `{items, next_cursor, snapshot_seq}`. Cursors are opaque, signed and bind the entity,\nthe filters, the ordering and the snapshot; pass them back unchanged. Default 50 per page, maximum\n200; events default 100, maximum 500. A cursor whose snapshot is gone is\n`409 cursor_expired` with a resync link.\n\n**Writes** require an `Idempotency-Key`. The same key with the same request replays the original status and body\nwith `Idempotency-Replayed: true`; the same key with a different request is `409 idempotency_conflict`.\n\n**Authorisation** records, it does not enforce. A credential is one opaque actor string scoped to explicit\nentities; that string is written to `created_by` and is never parsed. Every write is applied on the caller's own\nauthority and recorded with its actor and reason; there is no approval step.\n", "version": "1" }, "paths": { "/healthz": { "get": { "tags": [ "service" ], "summary": "Liveness", "operationId": "healthz_healthz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/readyz": { "get": { "tags": [ "service" ], "summary": "Readiness: migrations, the writer, the pinned verifier and the cursor keyring", "operationId": "readyz_readyz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } } } } }, "/v1/entities": { "get": { "tags": [ "service" ], "summary": "The entities this credential can see", "operationId": "list_entities_v1_entities_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityList" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } }, "post": { "tags": [ "service" ], "summary": "Create an entity: its database file, its schema, its commodities and its opening chart", "description": "Create a new set of books and serve them from this process immediately.\n\nThe reply is one ``EntitySummary``, the same object ``GET /v1/entities`` lists and\n``GET /v1/entities/{entity_id}`` returns, so the caller can follow ``links.capabilities`` straight into the\nnew book.\n\nCreating an entity that is already served is not an update. The id is its permanent address and the books\nbehind it are somebody's accounts, so a second creation is refused rather than merged. A retry of the same\ncreation (same credential, same ``Idempotency-Key``, same body) replays the original 201, so it is safe to\nretry over a connection that dropped after the books were written.", "operationId": "initialize_entity", "requestBody": { "content": { "application/json": { "schema": { "$defs": { "CommodityDeclaration": { "properties": { "code": { "type": "string", "title": "Code", "description": "the commodity's code, e.g. USD" }, "precision": { "type": "integer", "maximum": 6.0, "minimum": 0.0, "title": "Precision", "description": "decimal places this commodity is held to; 2 for USD, 0 for JPY" } }, "additionalProperties": false, "type": "object", "required": [ "code", "precision" ], "title": "CommodityDeclaration" } }, "properties": { "entity_id": { "type": "string", "title": "Entity Id", "description": "the entity's permanent address: 1-63 characters of lower-case letters, digits and hyphens", "examples": [ "acme-holdings" ] }, "legal_name": { "type": "string", "title": "Legal Name", "description": "the registered name, as it appears on the statements" }, "legal_form": { "type": "string", "title": "Legal Form", "description": "e.g. Ltd, Inc, B.V., S.L." }, "country": { "type": "string", "title": "Country", "description": "ISO country code" }, "base_currency": { "type": "string", "title": "Base Currency", "description": "the currency this entity's statements are presented in" }, "base_precision": { "type": "integer", "maximum": 6.0, "minimum": 0.0, "title": "Base Precision", "description": "decimal places for the base currency; 2 for USD, 0 for JPY" }, "commodities": { "items": { "$ref": "#/$defs/CommodityDeclaration" }, "type": "array", "title": "Commodities", "description": "further commodities beyond the base currency" }, "starter_chart": { "type": "boolean", "title": "Starter Chart", "description": "add the generic starter chart (cash, receivables, payables, general expenses, sales) as well as the retained-earnings equity account", "default": false }, "tax_regime": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Tax Regime", "description": "opaque, recorded on the entity row" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason", "description": "why this book exists; kept on the audit action" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "legal_form", "country", "base_currency", "base_precision" ], "title": "EntityCreationSubmission", "description": "Create one entity: its database file, its schema, its commodities and its opening chart.\n\nEverything here is supplied by the caller, because every part of it is permanent or nearly so. The id is\nthe entity's address in every URL and the name of the file it lives in, so it is a plain slug with no second\nspelling.\n\n``base_precision`` is explicit, as ``initialize_entity`` requires: defaulting to two decimals would silently\nhold a zero-decimal currency to hundredths, and every later amount would be wrong by a factor of a hundred\nwithout anything reporting it.\n\n``starter_chart`` defaults to false. A book about to be imported or authored wants its own chart, and\naccounts added by a default would have to be noticed and archived. Either way, the equity account an\nopening balance lands in is created by ``initialize_entity``; without it an entity cannot take an opening\nbalance at all." } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySummary" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "412": { "description": "Precondition Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "Unprocessable Content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "503": { "description": "Service Unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/entities/{entity_id}": { "get": { "tags": [ "entity" ], "summary": "One entity: who it is, what it holds and how far it is closed", "description": "The entity itself, in the same shape ``GET /v1/entities`` lists.\n\nThis is where every entity response's ``links.self`` points. It is built by the same code as the listing's\nitems, so the two cannot disagree about what an entity is.", "operationId": "entity_v1_entities__entity_id__get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySummary" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/capabilities": { "get": { "tags": [ "entity" ], "summary": "Permissions, published limits, the amount contract and the account/currency bindings", "operationId": "capabilities_v1_entities__entity_id__capabilities_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/accounts": { "get": { "tags": [ "accounts" ], "summary": "The chart of accounts", "operationId": "list_accounts_v1_entities__entity_id__accounts_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "type", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "asset | liability | equity | income | expense", "title": "Type" }, "description": "asset | liability | equity | income | expense" }, { "name": "archived", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Archived" } }, { "name": "text", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "substring of the account path or code", "title": "Text" }, "description": "substring of the account path or code" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } }, "post": { "tags": [ "accounts" ], "summary": "Add an account to the chart", "description": "Write one new account and return it as it now stands, so the caller can book to it without re-reading.\n\nA path already in the chart is a 409, not a second account with the same name. Two accounts that print\nidentically in every report is not a useful state, and the caller who hit it wanted the account it already\nhas.\n\nWrites an ``account.created`` audit action recording who extended the chart and why (issue 0006).", "operationId": "create_account", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartChangeResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Add one account to the chart.\n\nThe chart is authored, not derived: an account written here is permanent, every future report carries it,\nand the only way out is to archive it. So this asks for everything an account needs and infers nothing.\n\n``type`` cannot be read off the path. ``assets:...`` usually is an asset, but a chart may put a\ncontra-asset under ``assets`` or a recovery under ``expenses``, and a guess that lands an account on the\nwrong side of the balance sheet is wrong in every statement afterwards.\n\n``is_cash`` defaults to false. A cash account is one a bank statement is reconciled against, which is a\nfact about the real world rather than the books, and should not be acquired by leaving a field out.\n\n``reason`` is optional. The ``account.created`` audit action keeps whatever is given (issue 0006). Adding\nan account is structure rather than an assertion about what happened, so \"an account was added\" is the\nwhole content of the act, and is what the action records when no reason is given. Retiring an account is a\ndecision about the books, so ``POST /accounts/{id}/archive`` does require a reason.", "properties": { "path": { "description": "colon-separated, e.g. 'expenses:professional-services:audit'", "maxLength": 255, "minLength": 1, "title": "Path", "type": "string" }, "type": { "description": "asset | liability | equity | income | expense", "title": "Type", "type": "string" }, "commodities": { "description": "the currencies this account may hold; every account declares at least one", "items": { "type": "string" }, "minItems": 1, "title": "Commodities", "type": "array" }, "is_cash": { "default": false, "description": "true only for an account a bank statement is reconciled against", "title": "Is Cash", "type": "boolean" }, "code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "the chart code this account is known by, if any", "title": "Code" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied account id; generated when omitted", "title": "Id" }, "reason": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "why this account is being added; kept verbatim on the audit action. Omit it and the action records that an account was added to the chart", "title": "Reason" } }, "required": [ "path", "type", "commodities" ], "title": "AccountCreationSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/accounts/{account_id}/archive": { "post": { "tags": [ "accounts" ], "summary": "Retire an account: nothing may be posted to it again, and everything posted to it stays", "description": "Archive an account. This is the only way an account leaves the chart.\n\nNothing is deleted and no history moves: every entry already posted to the account stays where it is and\nkeeps appearing in every report that covers its date. From now on, a leg on the account is refused at\nposting time (``account_archived``). ``restore`` undoes this.\n\n``account_id`` accepts the account's path as well as its id, like everywhere an account is named in the\ncommand surface. A reason is required, and ``expected_version`` is the version the caller read.", "operationId": "archive_account", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartChangeResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Retire an account: nothing may be posted to it again, and everything already posted to it stays.\n\n``reason`` is required here, though optional on creation, because this is a decision about the books rather\nthan structure. An archived account stays visible in every later report, and \"why did this stop being\nused?\" is what a reviewer will ask.\n\n``expected_version`` is the account version the caller was looking at, the same concurrency check a close\nuses. If two callers retire an account from two readings of the chart, the second fails with\n``stale_version`` rather than acting on a chart it never saw.", "properties": { "reason": { "description": "why nothing may be posted to this account again", "minLength": 1, "title": "Reason", "type": "string" }, "expected_version": { "description": "the account version this caller read", "minimum": 1, "title": "Expected Version", "type": "integer" } }, "required": [ "reason", "expected_version" ], "title": "AccountArchiveSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/accounts/{account_id}/restore": { "post": { "tags": [ "accounts" ], "summary": "Put a retired account back in use, so what it still carries can be finished", "description": "Undo an archive. This is to ``archive_account`` what ``reopen_period`` is to ``close_period``.\n\nWhile an account is archived, reversing against it, correcting, booking to it and closing over it are all\nrefused ``account_archived``. Restoring is how an account archived while it still held a balance, a posted\nentry or an unbooked statement line gets finished.\n\nHistory does not move in either direction; a leg on this account is simply accepted again. A reason is\nrequired, as for archiving, and ``expected_version`` is the version the caller read.", "operationId": "restore_account", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartChangeResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Put a retired account back in use: the inverse of archiving, with the reason it had to come back.\n\nThis takes back an archive the way ``reopen_period`` takes back ``close_period``. History does not move\neither way. What comes back is the ability to post to the account, so a balance can be corrected, a\nstatement line booked and the period closed after an account was retired too early.", "properties": { "reason": { "description": "why this account is in use again", "minLength": 1, "title": "Reason", "type": "string" }, "expected_version": { "description": "the account version this caller read", "minimum": 1, "title": "Expected Version", "type": "integer" } }, "required": [ "reason", "expected_version" ], "title": "AccountRestoreSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/accounts/{account_id}": { "get": { "tags": [ "accounts" ], "summary": "One account", "operationId": "get_account_v1_entities__entity_id__accounts__account_id__get", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/accounts/{account_id}/register": { "get": { "tags": [ "accounts" ], "summary": "Movements and running balances of one account over a date range", "operationId": "account_register_v1_entities__entity_id__accounts__account_id__register_get", "parameters": [ { "name": "account_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Account Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "From" }, "description": "inclusive" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "To" }, "description": "inclusive" }, { "name": "commodity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commodity" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Register" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries": { "post": { "tags": [ "entries" ], "summary": "Write a balanced journal entry: an accrual, a reclassification, an adjustment", "description": "Post one balanced journal entry that no bank statement line stands behind.\n\nAn invoice raised, a payroll accrued, a quarter's withholding moved from one liability to the next: each is\nan economic event on a date with no cash row behind it on that date. The other entry writes either hang an\nentry off a statement line or post a converted set as one unit (``POST /batches``). This one is for a single\nentry, and without it a period's profit could only ever be its cash flow.\n\nThe entry takes the ordinary posting path (drafted and sealed in one transaction), so it meets the same\nbalance rule, the same account, currency and precision rules and the same period lock as a line classified\noff a statement. It takes any number of legs from two upward, as a four-leg payroll accrual needs. It\ncomes back posted and is never edited: ``POST /entries/{id}/correct`` restates it and\n``POST /entries/{id}/reverse`` withdraws it.", "operationId": "post_entry", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JournalEntryResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "EntryLeg": { "additionalProperties": false, "description": "One leg of a manual journal entry: an account, a currency and a signed amount.\n\nUnlike a line booking's legs, these are the whole entry. No cash leg is supplied for you, because there is\nno statement line behind this entry. Two legs or more, netting to zero per commodity.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "amount": { "description": "signed decimal amount in whole commodity units; never a JSON number", "examples": [ "-12.00" ], "title": "Amount", "type": "string" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "required": [ "account", "commodity", "amount" ], "title": "EntryLeg", "type": "object" } }, "additionalProperties": false, "description": "Write one balanced entry directly into the books: an accrual, a reclassification, an adjustment.\n\nThis is how the books record what a bank statement does not: an invoice raised, a payroll accrued, a\nquarter's withholding moved from one liability to the next. Without it a ledger can only record cash, and\na period's profit is not a cash-flow figure.\n\nThe entry is posted when it is written; there is no approval step. A posted entry is never edited. It is\ncorrected with ``POST /entries/{id}/correct`` (a mirror that cancels it plus a replacement, in one\ntransaction) or withdrawn with ``POST /entries/{id}/reverse``.\n\n``reason`` is required and is kept verbatim on the append-only audit action. ``narration`` is what the entry\nreads as in every report and export; ``reason`` is why it was written.", "properties": { "legs": { "description": "every leg of the entry; they net to zero per commodity", "items": { "$ref": "#/$defs/EntryLeg" }, "minItems": 2, "title": "Legs", "type": "array" }, "dt": { "description": "the entry date, YYYY-MM-DD; a date in a closed month is refused", "title": "Dt", "type": "string" }, "narration": { "description": "what this entry reads as in the books", "maxLength": 4096, "minLength": 1, "title": "Narration", "type": "string" }, "reason": { "description": "why it is being written; kept in the record", "minLength": 1, "title": "Reason", "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "entries.origin; defaults to 'manual'. 'invoice', 'payroll' and 'adjustment' are the other ordinary ones here", "title": "Origin" }, "code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "hledger tcode, e.g. a document number", "title": "Code" }, "comment": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "description": "hledger tcomment, kept verbatim", "title": "Comment" }, "tags": { "anyOf": [ { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "description": "[name, value] pairs, in comment order", "title": "Tags" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied entry id; generated when omitted", "title": "Id" } }, "required": [ "legs", "dt", "narration", "reason" ], "title": "JournalEntrySubmission", "type": "object" } } } } }, "get": { "tags": [ "entries" ], "summary": "Entries, filtered", "operationId": "list_entries_v1_entities__entity_id__entries_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "status", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "draft | posted | void", "title": "Status" }, "description": "draft | posted | void" }, { "name": "origin", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Origin" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "From" }, "description": "inclusive" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "To" }, "description": "inclusive" }, { "name": "account", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "only entries with a leg on this account", "title": "Account" }, "description": "only entries with a leg on this account" }, { "name": "text", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "substring of the narration", "title": "Text" }, "description": "substring of the narration" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries/{entry_id}": { "get": { "tags": [ "entries" ], "summary": "One entry: its legs, what it is now, and every correction it is part of", "description": "Return one entry with its legs, its current ``state`` and every correction it is part of (issue 0007).\n\nReviewing an entry means knowing what it is now: posted, corrected or reversed. That is not a column. It\nfollows from the correction rows that name the entry and is derived in one place (``views.entry_state``).\n\n``corrections`` is the chain from whichever end this entry sits on, so a mirror links back to what it\nreversed rather than reading as a lone negative entry.", "operationId": "get_entry_v1_entities__entity_id__entries__entry_id__get", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/events": { "get": { "tags": [ "entries" ], "summary": "History of one entry: its posting, its corrections and what was filed against it", "operationId": "entry_events_v1_entities__entity_id__entries__entry_id__events_get", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Since" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryEvents" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/reverse": { "post": { "tags": [ "entries" ], "summary": "Reverse a posted entry, recording why somebody disagreed with it", "description": "Withdraw a posted entry without restating it; ``POST /entries/{id}/correct`` withdraws and restates.\n\nNothing is edited or deleted. The original stays posted and in the sums, an exact mirror is posted beside\nit, and both carry the actor that wrote them. A reversal that would land in a closed month is refused;\nreopen the month to fix it.\n\nTo move a statement line onto a different account, use ``POST /lines/{id}/reexplain``, which does this and\nthe re-booking together so the line is never momentarily unexplained.", "operationId": "reverse_entry", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryReversal" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Disagree with a posted entry: an exact mirror is posted beside it, and both stay standing.\n\n``reason`` is required and is recorded verbatim on the append-only audit action. A year later the numbers\nspeak for themselves, but why somebody disagreed is not recoverable from anywhere else.", "properties": { "reason": { "description": "why this booking is wrong; recorded verbatim", "minLength": 1, "title": "Reason", "type": "string" }, "dt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "the mirror's date; defaults to the original's", "title": "Dt" }, "narration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "the mirror's narration; defaults to naming the original", "title": "Narration" } }, "required": [ "reason" ], "title": "EntryReversalSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/correct": { "post": { "tags": [ "entries" ], "summary": "Reverse a posted entry and post what it should have said, in one transaction", "description": "Reverse a posted entry and post what it should have said, linked to the original (issue 0006).\n\n``reverse`` withdraws a booking; this restates it, which is the ordinary case. An entry on the wrong\naccount, for the wrong amount or on the wrong date usually needs replacing, not just withdrawing.\n\nBoth halves land in one transaction, so there is no moment at which the original is reversed and nothing\nstands in its place, and a concurrent report cannot see the books with the entry missing. The replacement\nis an ordinary entry (account paths and exact decimal amounts) and goes through the same balance, account,\nprecision and period-lock rules as any other posting. A correction that would land in a closed month is\nrefused; reopen the month to fix it.\n\nFor a statement line, ``POST /lines/{id}/reexplain`` does this and the re-explanation together, so the line\nis never momentarily unexplained.", "operationId": "correct_entry", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryCorrection" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "EntryLeg": { "additionalProperties": false, "description": "One leg of a manual journal entry: an account, a currency and a signed amount.\n\nUnlike a line booking's legs, these are the whole entry. No cash leg is supplied for you, because there is\nno statement line behind this entry. Two legs or more, netting to zero per commodity.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "amount": { "description": "signed decimal amount in whole commodity units; never a JSON number", "examples": [ "-12.00" ], "title": "Amount", "type": "string" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "required": [ "account", "commodity", "amount" ], "title": "EntryLeg", "type": "object" }, "EntryReplacement": { "additionalProperties": false, "description": "What the corrected entry should have said: the same shape as writing one, minus the reason.\n\nThere is one reason for the whole correction, and it belongs to the correction, not the replacement. A\nseparate reason on the replacement would invite two different sentences about one act.", "properties": { "legs": { "description": "every leg of the replacement; nets to zero per commodity", "items": { "$ref": "#/$defs/EntryLeg" }, "minItems": 2, "title": "Legs", "type": "array" }, "dt": { "description": "the replacement's date, YYYY-MM-DD", "title": "Dt", "type": "string" }, "narration": { "maxLength": 4096, "minLength": 1, "title": "Narration", "type": "string" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "entries.origin; defaults to 'manual'", "title": "Origin" }, "code": { "default": "", "description": "hledger tcode", "maxLength": 255, "title": "Code", "type": "string" }, "comment": { "default": "", "maxLength": 4096, "title": "Comment", "type": "string" }, "tags": { "anyOf": [ { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "description": "[name, value] pairs, in comment order", "title": "Tags" } }, "required": [ "legs", "dt", "narration" ], "title": "EntryReplacement", "type": "object" } }, "additionalProperties": false, "description": "Reverse a posted entry and post what it should have said, in one transaction.\n\nA reversal says only \"this was wrong\". A correction says what was meant, which is the ordinary case: an\nentry booked to the wrong account, for the wrong amount or on the wrong date is restated, not just\nwithdrawn. Doing both in one command means the books never pass through a state, visible to a concurrent\nreport, where the original is reversed and nothing stands in its place.\n\nNothing is edited. The original stays posted and in the sums, an exact mirror is posted beside it, and the\nreplacement is posted as its own entry. All three carry the actor that wrote them, and one\n``entry.corrected`` audit action records why.", "properties": { "reason": { "description": "why the original was wrong; recorded verbatim", "minLength": 1, "title": "Reason", "type": "string" }, "replacement": { "$ref": "#/$defs/EntryReplacement" }, "dt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "the mirror's date; defaults to the original's", "title": "Dt" }, "narration": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "the mirror's narration; defaults to naming the original", "title": "Narration" } }, "required": [ "reason", "replacement" ], "title": "EntryCorrectionSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/batches": { "post": { "tags": [ "entries" ], "summary": "Post many entries as one unit, checked against the count and totals the caller asserts", "description": "Post a converted set of entries, and learn before anything commits whether it is the set you sent.\n\nThe caller asserts how many entries the batch contains and what each commodity's debits and credits come to\nin micros. Both sides are asked for even though a balanced batch makes them equal. The caller computes them\nfrom its own source, so a figure transposed on one side disagrees with the other instead of cancelling out.\n\nA refusal is whole and leaves nothing behind, whether the cause is a broken assertion, an unknown account in\nthe nine-hundredth entry or a date in a closed period. ``422 unbalanced`` names every commodity whose asserted\ntotals disagree with what was posted, with both numbers. ``422 validation`` covers the count and the maximum\nbatch size (published as ``limits.max_batch_entries`` in ``/capabilities``). A refusal about one entry names\nthat entry: ``batch_index``, its date and narration, its ``entry_id`` when the caller supplied one, and a\n``path`` such as ``entries[900].legs[0].account``. A retry under the same ``Idempotency-Key`` replays the\noriginal reply instead of posting the batch twice.\n\nThe whole batch is recorded as one ``operations`` row (intent: the assertion; result: the entries written),\nalongside the ordinary audit action each entry keeps.", "operationId": "post_batch", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "BatchAssertion": { "additionalProperties": false, "description": "What the caller says this batch contains: the caller's claim, not the ledger's derivation.\n\nThe ledger never sees the journal, spreadsheet or export the entries were converted from (``decisions.md``,\n\"Chunk F1 -- the generic statement input\"), so it cannot know how many entries there should be. The caller\ncounted them at the source and states it here, and the ledger refuses a batch that does not match.", "properties": { "count": { "description": "how many entries this batch contains", "minimum": 1, "title": "Count", "type": "integer" }, "totals": { "description": "every commodity the batch touches, each named exactly once", "items": { "$ref": "#/$defs/BatchTotal" }, "minItems": 1, "title": "Totals", "type": "array" } }, "required": [ "count", "totals" ], "title": "BatchAssertion", "type": "object" }, "BatchEntry": { "additionalProperties": false, "description": "One entry of a batch, in the same shape ``POST /entries`` takes.\n\nThe only difference is that ``reason`` is optional, because the batch has one and repeating it on every entry\nof a converted year would be a thousand copies of one sentence. An entry with something more specific to\nsay carries its own, recorded verbatim on that entry's audit action.", "properties": { "legs": { "description": "every leg of the entry; they net to zero per commodity", "items": { "$ref": "#/$defs/EntryLeg" }, "minItems": 2, "title": "Legs", "type": "array" }, "dt": { "description": "the entry date, YYYY-MM-DD", "title": "Dt", "type": "string" }, "narration": { "description": "what this entry reads as in the books", "maxLength": 4096, "minLength": 1, "title": "Narration", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "why this entry in particular was written; defaults to the batch's", "title": "Reason" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "entries.origin; defaults to 'manual'", "title": "Origin" }, "code": { "default": "", "description": "hledger tcode, e.g. a document number", "maxLength": 255, "title": "Code", "type": "string" }, "comment": { "default": "", "description": "hledger tcomment, kept verbatim", "maxLength": 4096, "title": "Comment", "type": "string" }, "tags": { "anyOf": [ { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "description": "[name, value] pairs, in comment order", "title": "Tags" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied entry id; generated when omitted", "title": "Id" } }, "required": [ "legs", "dt", "narration" ], "title": "BatchEntry", "type": "object" }, "BatchTotal": { "additionalProperties": false, "description": "What the caller says one commodity comes to across the whole batch, as two magnitudes in micros.\n\nBoth are non-negative: ``debits_micros`` is the sum of every positive posting of this commodity and\n``credits_micros`` of every negative one. Each entry balances, so the two must be equal once the batch is\nbuilt, and that is why both are asked for. The caller computes them from its own source, so a figure\ntransposed on one side of the conversion disagrees with the other and the batch is refused.", "properties": { "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "debits_micros": { "description": "sum of the positive postings of this commodity, in micros", "examples": [ "1200000" ], "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Debits Micros", "type": "string" }, "credits_micros": { "description": "sum of the negative postings of this commodity, as a magnitude", "examples": [ "1200000" ], "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Credits Micros", "type": "string" } }, "required": [ "commodity", "debits_micros", "credits_micros" ], "title": "BatchTotal", "type": "object" }, "EntryLeg": { "additionalProperties": false, "description": "One leg of a manual journal entry: an account, a currency and a signed amount.\n\nUnlike a line booking's legs, these are the whole entry. No cash leg is supplied for you, because there is\nno statement line behind this entry. Two legs or more, netting to zero per commodity.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "amount": { "description": "signed decimal amount in whole commodity units; never a JSON number", "examples": [ "-12.00" ], "title": "Amount", "type": "string" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "required": [ "account", "commodity", "amount" ], "title": "EntryLeg", "type": "object" } }, "additionalProperties": false, "description": "N entries, posted as one unit that is applied whole or refused whole.\n\nThis is the write for a conversion: a year of entries an agent has converted from a journal, a spreadsheet or\nanother system's export. A loop of single ``POST /entries`` calls posts the same rows but proves nothing\nabout the set. A dropped entry, a retry that posted twice, or a connection lost two thirds of the way\nthrough each leave books that are internally consistent and simply wrong. A batch carries the caller's own\ncount and per-commodity totals, and either matches them or leaves nothing behind.", "properties": { "reason": { "description": "why this batch is being loaded; kept in the record", "minLength": 1, "title": "Reason", "type": "string" }, "entries": { "description": "the entries, in the order they are to be posted", "items": { "$ref": "#/$defs/BatchEntry" }, "minItems": 1, "title": "Entries", "type": "array" }, "asserted": { "$ref": "#/$defs/BatchAssertion" } }, "required": [ "reason", "entries", "asserted" ], "title": "BatchSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/reports/trial-balance": { "get": { "tags": [ "reports" ], "summary": "Trial balance of the continuous journal through a date", "operationId": "get_trial_balance_v1_entities__entity_id__reports_trial_balance_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive; the latest posting when omitted", "title": "As Of" }, "description": "inclusive; the latest posting when omitted" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialBalance" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/reports/balance-sheet": { "get": { "tags": [ "reports" ], "summary": "Balance sheet of the continuous journal as at a date", "operationId": "get_balance_sheet_v1_entities__entity_id__reports_balance_sheet_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "as_of", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive; the latest posting when omitted", "title": "As Of" }, "description": "inclusive; the latest posting when omitted" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceSheet" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/reports/income-statement": { "get": { "tags": [ "reports" ], "summary": "Income and expense movements of a range (openings excluded)", "operationId": "get_income_statement_v1_entities__entity_id__reports_income_statement_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "From" }, "description": "inclusive" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "To" }, "description": "inclusive" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomeStatement" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/reports/composition": { "get": { "tags": [ "reports" ], "summary": "What a period's figures were built from: posted entries by origin and by source journal", "description": "Count a period's posted entries per ``origin`` and per source journal. Counts, not a verdict.\n\nA reader looking at a nearly empty income statement wants to know whether that is what the books say or only\nwhat has been loaded so far. The other reports cannot tell, because an absent invoice looks the same as one\nnever issued. Here, a book loaded from its bank statement alone and a book with nothing to report look\ndifferent, and neither is called wrong.", "operationId": "get_composition_v1_entities__entity_id__reports_composition_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "From" }, "description": "inclusive" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "To" }, "description": "inclusive" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Composition" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/reports/statements": { "get": { "tags": [ "reports" ], "summary": "The income statement and balance sheet of a period, arranged and signed by the service", "description": "Return the statements the PDF is drawn from, as JSON, so a screen and an emailed document cannot disagree.\n\nThis is the canonical shaped view from issue 0008 section B. Sections, their order, signs, subtotals, the\nresult row and whether the two sides of the sheet meet are decided once in ``haddon.statements.shape``. The\ninterface reads that arrangement instead of rebuilding it, and the PDF is drawn from the same view.\n``difference`` and its per-column ``checks`` are part of the output, which keeps JSON, interface and PDF in\nagreement mid-period when equity carries a result nothing has posted to it.\n\nEvery commodity the period holds comes back shaped, the requested one first. ``other_commodities`` names the\nrest, so a reader is told what a single-commodity statement leaves out.", "operationId": "get_statements_v1_entities__entity_id__reports_statements_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "From" }, "description": "inclusive" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "To" }, "description": "inclusive" }, { "name": "comparative", "in": "query", "required": false, "schema": { "type": "boolean", "description": "show the period before this one beside it, when these books hold one", "default": true, "title": "Comparative" }, "description": "show the period before this one beside it, when these books hold one" }, { "name": "commodity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "defaults to the entity's base currency", "title": "Commodity" }, "description": "defaults to the entity's base currency" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementsDocument" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/reports/statements.pdf": { "get": { "tags": [ "reports" ], "summary": "Income statement and balance sheet of one period, as a PDF", "description": "Render the income statement and balance sheet as one PDF, drawn by the service rather than a browser.\n\nSame journal, same period and same figures as the JSON reports. The shaping is ``haddon.statements``, the\none place the sign convention, the grouping and the period result line are decided, so this document and any\nother reader of ``/reports`` cannot disagree about a total.\n\nThe period names itself. ``from``/``to`` are the only period input, and whether that range is a calendar\nyear, quarter or month is worked out from the bounds (``haddon.statements.period``). A caller who could name\na granularity could name one its own dates contradict, and a PDF outlives the request that made it.\n\nA balance sheet is at a date. It is drawn as at the period's last day and headed that way, and its\ncomparative is the last day of the comparative period, never a range. Equity carries the income and expense\nmovements from the start of the journal to that date, which is what makes the two sides meet. The sheet is\ncumulative, so a result row covering only the requested period would leave earlier profit in neither equity\nnor the result line, and any range not starting at the journal's start would print a difference.\n``web/src/routes/Reports.tsx`` asks for the same open start.", "operationId": "get_statements_pdf_v1_entities__entity_id__reports_statements_pdf_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "From" }, "description": "inclusive" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive", "title": "To" }, "description": "inclusive" }, { "name": "comparative", "in": "query", "required": false, "schema": { "type": "boolean", "description": "show the period before this one beside it, when these books hold one", "default": true, "title": "Comparative" }, "description": "show the period before this one beside it, when these books hold one" }, { "name": "commodity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "defaults to the entity's base currency", "title": "Commodity" }, "description": "defaults to the entity's base currency" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/pdf": {} } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/events": { "get": { "tags": [ "events" ], "summary": "Ordered events after a sequence", "operationId": "list_events_v1_entities__entity_id__events_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "since", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0, "title": "Since" } }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/snapshots/{snapshot_id}": { "get": { "tags": [ "artifacts" ], "summary": "One immutable report snapshot: its state hash, manifest, report and checks", "operationId": "get_snapshot_v1_entities__entity_id__snapshots__snapshot_id__get", "parameters": [ { "name": "snapshot_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Snapshot Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/exports/{export_id}": { "get": { "tags": [ "artifacts" ], "summary": "One immutable export: artifacts, manifest digest and the verifier's verdict", "operationId": "get_export_v1_entities__entity_id__exports__export_id__get", "parameters": [ { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Export Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/exports": { "post": { "tags": [ "artifacts" ], "summary": "Export a range of this book as hledger journal files, verified by the pinned binary", "description": "Render the books as a journal anybody can read with hledger, and record that it was done.\n\nThis is the same export ``bin/haddon-export`` runs on the machine. It reads the store, renders\ndeterministically, stages the files, runs ``hledger check --strict`` on them under the pinned binary,\npublishes them only if that passes, and then writes one ``export`` operation, a snapshot, the immutable\n``exports`` row and an ``export.completed`` event. A strict-check failure publishes nothing and records\nnothing.\n\nThe reply is recorded in the same transaction as the export (``export_book(also_record=...)``), so a retry\nunder the same ``Idempotency-Key`` replays the original 201 instead of exporting again, and there is no\nwindow in which the export is durable and its reply is not. Two exports of one entity are serialised,\nbecause the directory they publish into is exclusively managed.\n\nThe work runs in a worker thread. Every other write here is a few SQLite statements; this one renders a\nwhole range and waits on a subprocess, which on the event loop would stop the process answering anything,\n``/healthz`` included, until it finished. The lock is taken inside that thread for the same reason.\n\nA range with nothing posted in it is refused (``422``): an empty directory is not an export.", "operationId": "run_export", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportRun" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Which range of this book to render as hledger journal files.\n\nThe default is the whole journal, which is the exporter's own default: a journal is continuous (issue 0002),\nso there is no natural default year. ``year`` is only a calendar-year shorthand, exactly ``from`` the first\nof January ``to`` the thirty-first of December, and may not be combined with either bound. Either bound may\nbe left open on its own, in which case it is filled from what is actually posted.\n\nThere is no ``reason``. Every write that decides something takes one; an export decides nothing, it reads\nthe book and renders it (``docs/design/decisions.md``, \"Chunk C2a\"). What is recorded is the range, the\nactor and the state that was rendered.", "properties": { "year": { "anyOf": [ { "maximum": 9999, "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "calendar-year shorthand for from/to; not combined with either", "title": "Year" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive first day of the range (YYYY-MM-DD); omit for the first posting", "title": "From" }, "to": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive last day of the range (YYYY-MM-DD); omit for the last posting", "title": "To" }, "overwrite": { "default": true, "description": "replace an export already published for this range. True by default: the directory holds one export per range and is exclusively managed by this service, so there is nothing of anybody else's to overwrite -- an unmanaged file in it refuses the whole export either way", "title": "Overwrite", "type": "boolean" } }, "title": "ExportSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/exports/{export_id}/artifacts/{artifact}": { "get": { "tags": [ "artifacts" ], "summary": "One file this export published, verified against the digest in the export row", "description": "Return one published journal file, the form of these books other tools can read.\n\nThe name is a key into the export's immutable artifact list, not a path. A name the export did not record\nis a 404 before any path is built from it, and the file is read only from under this entity's configured\nexport root. It is re-hashed against the ``sha256`` the row recorded before any byte is returned. That\ndigest is the claim that these bytes passed the pinned verifier, so a file that no longer matches is refused\nrather than served with a warning (:mod:`haddon.api.exported`).\n\nAn export published elsewhere, for example by ``bin/haddon-export`` into an operator's own directory, is\nrecorded here but its bytes are not served: they are not under the root this service serves from.", "operationId": "export_artifact_v1_entities__entity_id__exports__export_id__artifacts__artifact__get", "parameters": [ { "name": "export_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Export Id" } }, { "name": "artifact", "in": "path", "required": true, "schema": { "type": "string", "title": "Artifact" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(attachment|inline)$", "description": "a journal is plain text, so both are honoured", "default": "attachment", "title": "Disposition" }, "description": "a journal is plain text, so both are honoured" } ], "responses": { "200": { "description": "one published journal file, re-hashed against what was recorded", "content": { "text/plain": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/close-checks": { "get": { "tags": [ "close" ], "summary": "Close eligibility through a date: per check, a status, a reason and the outstanding items", "operationId": "get_close_checks_v1_entities__entity_id__close_checks_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "through", "in": "query", "required": true, "schema": { "type": "string", "description": "the close date this would close through (YYYY-MM-DD)", "title": "Through" }, "description": "the close date this would close through (YYYY-MM-DD)" }, { "name": "override", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "check keys to preview an override of; the reason belongs on the close itself, not on a preview", "title": "Override" }, "description": "check keys to preview an override of; the reason belongs on the close itself, not on a preview" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseChecks" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/closes/{close_id}": { "get": { "tags": [ "close" ], "summary": "One close or reopen, read back, with a link to the snapshot it was recorded against", "description": "Read one close or reopen record, linking to the immutable snapshot behind it (issue 0005, criterion 6).\n\nA close returns its snapshot link only once, in the 201. This route is the way back to it afterwards. The\nlock carries the id of the close that set it (``lock_close_id`` on the entity summary), so from any closed\nperiod this is one hop.\n\nRead-only, and shaped like ``/snapshots/{id}`` and ``/exports/{id}``. A close record is an immutable row,\nnever updated or deleted, so it is fetched by id and there is no listing here. The history of closes belongs\nto the reviewer loop (issue 0007).", "operationId": "get_close_record_v1_entities__entity_id__closes__close_id__get", "parameters": [ { "name": "close_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Close Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CloseRecord" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/close": { "post": { "tags": [ "close" ], "summary": "Close the books through a date: check, snapshot, lock and audit, in one transaction", "description": "Close a period on the acting principal's own authority, with the checks applied.\n\nEverything happens in one transaction. The checks are evaluated, and a blocking one refuses unless an\noverride names it. The verification snapshot is computed and stored, the lock advances, and one audit action\nrecords what was evaluated, what was waived and the snapshot's hash. A refusal leaves nothing behind: no\nsnapshot, no partial record, and the idempotency key is not used up.\n\nThere are two distinct refusals. ``409 close_not_eligible`` names every blocking check and what is\noutstanding in it. A ``422`` says an override named a check that is not blocking at all.", "operationId": "close_period", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClosePeriodResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "CloseOverride": { "additionalProperties": false, "description": "Close over one named blocking check: the check, and why. There is no id to pre-create and no wildcard.\n\nAn override is matched against the checks as the server has just evaluated them, so it can only name a\nfailure that is real at this moment. A blanket bypass cannot be expressed. Each override is stored on the\nclose record with the check's status and outstanding count as they stood, the acting principal and this\nreason.", "properties": { "check": { "description": "the check key this override answers, e.g. 'statement_coverage'", "minLength": 1, "title": "Check", "type": "string" }, "reason": { "description": "why this period is being closed with that check unsatisfied", "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "check", "reason" ], "title": "CloseOverride", "type": "object" } }, "additionalProperties": false, "description": "Shut the books through a date.\n\nA date, a reason, the lock version you believe is current and, only where a check is blocking, an override\nnaming that check and saying why. Nothing else: the verification snapshot is computed by the server,\nbecause a caller that could supply one could supply a hash of a state that never existed.\n\n``expected_version`` guards against two agents closing the same books from different readings of them; the\nsecond fails with ``stale_version`` and writes nothing. Retrying the same intent is a different matter,\nhandled by ``Idempotency-Key``.", "properties": { "through": { "description": "close through this date, inclusive (YYYY-MM-DD)", "title": "Through", "type": "string" }, "reason": { "description": "why the period is being closed; kept verbatim in the record", "minLength": 1, "title": "Reason", "type": "string" }, "expected_version": { "description": "the period lock version this close expects to advance", "minimum": 1, "title": "Expected Version", "type": "integer" }, "overrides": { "description": "one per blocking check being closed over", "items": { "$ref": "#/$defs/CloseOverride" }, "title": "Overrides", "type": "array" } }, "required": [ "through", "reason", "expected_version" ], "title": "ClosePeriodSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/reopen": { "post": { "tags": [ "close" ], "summary": "Move the period lock deliberately backwards, and record why", "description": "Open a closed period again.\n\nReopening is how an incomplete month gets fixed, so it does not depend on the checks that refuse a close\n(issue 0005, pitfall 1). The month that most needs reopening is exactly the one that cannot pass them.\nNothing is undone: the close record and its snapshot stay as they are, and this appends a second record\nsaying the lock moved back.", "operationId": "reopen_period", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReopenPeriodResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Move the lock deliberately backwards, and say why.\n\nGive exactly one of ``through`` or ``close_id``. ``through`` is a boundary (\"open March again\");\n``close_id`` is an action (\"undo that close\") and resolves to the boundary that close advanced from.\n\nA reopen is not gated on the close checks, because the month that most needs reopening is the one that\ncannot pass them. Nothing is undone: the close record and its snapshot stay where they are.", "properties": { "through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "reopen back to this date, inclusive (YYYY-MM-DD)", "title": "Through" }, "close_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "the close to undo; resolves to its prior boundary", "title": "Close Id" }, "reason": { "description": "why a closed period is being opened again", "minLength": 1, "title": "Reason", "type": "string" }, "expected_version": { "description": "the period lock version this reopen expects to move", "minimum": 1, "title": "Expected Version", "type": "integer" } }, "required": [ "reason", "expected_version" ], "title": "ReopenPeriodSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/reconciliation": { "get": { "tags": [ "reconciliation" ], "summary": "Bank against books: what the loaded statements say a cash account held, and what the ledger says", "description": "Compare statement and ledger balances at any date, not only where the bank printed a balance.\n\nBalances are always cumulative to ``as_of``. ``from`` narrows only the coverage answer (\"which days of the\nperiod I am looking at have no statement loaded\"). A balance is not a period figure, so ``from`` never\nchanges it.", "operationId": "get_reconciliation_v1_entities__entity_id__reconciliation_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "as_of", "in": "query", "required": true, "schema": { "type": "string", "description": "the date to compare at (YYYY-MM-DD)", "title": "As Of" }, "description": "the date to compare at (YYYY-MM-DD)" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "start of the period whose statement coverage is reported; defaults to the first of as_of's month", "title": "From" }, "description": "start of the period whose statement coverage is reported; defaults to the first of as_of's month" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reconciliation" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/statements": { "post": { "tags": [ "statements" ], "summary": "Load one statement: an account, a period, an opening and closing balance, lines, and the document", "operationId": "load_statement", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementWriteResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "StatementDocument": { "additionalProperties": false, "description": "The original document, by reference. The ledger records this and does not fetch it.\n\n``sha256`` is the hash of the bytes the agent read, and the key that makes a second load of the same\nstatement a refusal. Give exactly one of ``blob_path`` (bytes this service holds) and ``external_ref``\n(bytes held elsewhere).", "properties": { "sha256": { "description": "SHA-256 of the original document, 64 lowercase hex characters", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "title": "Sha256", "type": "string" }, "filename": { "maxLength": 512, "minLength": 1, "title": "Filename", "type": "string" }, "media_type": { "maxLength": 255, "minLength": 1, "title": "Media Type", "type": "string" }, "size_bytes": { "description": "size of the original document in bytes", "minimum": 0, "title": "Size Bytes", "type": "integer" }, "blob_path": { "default": "", "description": "where the original document is kept", "maxLength": 2048, "title": "Blob Path", "type": "string" }, "external_ref": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "a reference to bytes held elsewhere, when we hold none", "title": "External Ref" } }, "required": [ "sha256", "filename", "media_type", "size_bytes" ], "title": "StatementDocument", "type": "object" }, "StatementLineSubmission": { "additionalProperties": false, "description": "One normalised statement line.\n\n``currency`` is required and must equal the statement's commodity: the ledger declares currency, it never\ninfers it.", "properties": { "dt": { "description": "the line's value date (YYYY-MM-DD); must fall inside the declared period", "title": "Dt", "type": "string" }, "description": { "maxLength": 4096, "minLength": 1, "title": "Description", "type": "string" }, "amount": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Amount", "type": "string" }, "currency": { "maxLength": 64, "minLength": 1, "title": "Currency", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "the document's own reference for this line, when it has one", "title": "Reference" }, "raw": { "anyOf": [ { "maxLength": 8192, "type": "string" }, { "type": "null" } ], "description": "the line exactly as it appeared in the document, when that can be given", "title": "Raw" }, "source_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "the line's stable identity in the document; derived when omitted", "title": "Source Key" } }, "required": [ "dt", "description", "amount", "currency" ], "title": "StatementLineSubmission", "type": "object" } }, "additionalProperties": false, "description": "A statement: one account, one period, an opening and a closing balance, a list of lines, and the document.\n\nThere is no file format here. Haddon parses nothing: whatever the bank produced (CSV, XLSX, PDF, a pasted\ntable) is read outside the ledger and submitted as normalised lines. The ledger enforces what a parser must\nnot be trusted with, and refuses the whole submission if any of it fails:\n\n1. the lines must sum to ``closing`` minus ``opening``;\n2. every line's ``dt`` must fall inside ``period_start``..``period_end``;\n3. the currency must be declared, on the statement and on every line, and they must agree;\n4. the same document cannot be loaded twice (by ``document.sha256``).\n\n``opening`` is checked against the closing balance already recorded for the period ending the day before,\nand a disagreement is refused. When there is no such record the statement is still accepted, and the\nresponse says ``opening_verified: false`` with an ``opening_basis`` naming why. It is never assumed to be 0.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "period_start": { "description": "first day of the statement period (YYYY-MM-DD)", "title": "Period Start", "type": "string" }, "period_end": { "description": "last day of the statement period; inclusive, and free to cross a year", "title": "Period End", "type": "string" }, "opening": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Opening", "type": "string" }, "closing": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Closing", "type": "string" }, "lines": { "items": { "$ref": "#/$defs/StatementLineSubmission" }, "title": "Lines", "type": "array" }, "document": { "$ref": "#/$defs/StatementDocument" }, "locator": { "description": "where in the document the closing balance is printed", "maxLength": 512, "minLength": 1, "title": "Locator", "type": "string" }, "page": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "page of the document the closing balance is on", "title": "Page" }, "reason": { "description": "why this statement is being loaded; kept in the record", "minLength": 1, "title": "Reason", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied statement id; generated when omitted", "title": "Id" } }, "required": [ "account", "commodity", "period_start", "period_end", "opening", "closing", "document", "locator", "reason" ], "title": "StatementSubmission", "type": "object" } } } } }, "get": { "tags": [ "statements" ], "summary": "Loaded statements, newest listing order, filtered by account, commodity or date range", "operationId": "list_statements_v1_entities__entity_id__statements_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "commodity", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Commodity" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive, on the statement period", "title": "From" }, "description": "inclusive, on the statement period" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive, on the statement period", "title": "To" }, "description": "inclusive, on the statement period" }, { "name": "live", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "keep only statements nothing has replaced", "title": "Live" }, "description": "keep only statements nothing has replaced" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/statements/{statement_id}/replace": { "post": { "tags": [ "statements" ], "summary": "Replace a statement loaded wrongly; the predecessor is kept and visibly linked", "operationId": "replace_statement", "parameters": [ { "name": "statement_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Statement Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementWriteResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "StatementDocument": { "additionalProperties": false, "description": "The original document, by reference. The ledger records this and does not fetch it.\n\n``sha256`` is the hash of the bytes the agent read, and the key that makes a second load of the same\nstatement a refusal. Give exactly one of ``blob_path`` (bytes this service holds) and ``external_ref``\n(bytes held elsewhere).", "properties": { "sha256": { "description": "SHA-256 of the original document, 64 lowercase hex characters", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "title": "Sha256", "type": "string" }, "filename": { "maxLength": 512, "minLength": 1, "title": "Filename", "type": "string" }, "media_type": { "maxLength": 255, "minLength": 1, "title": "Media Type", "type": "string" }, "size_bytes": { "description": "size of the original document in bytes", "minimum": 0, "title": "Size Bytes", "type": "integer" }, "blob_path": { "default": "", "description": "where the original document is kept", "maxLength": 2048, "title": "Blob Path", "type": "string" }, "external_ref": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "a reference to bytes held elsewhere, when we hold none", "title": "External Ref" } }, "required": [ "sha256", "filename", "media_type", "size_bytes" ], "title": "StatementDocument", "type": "object" }, "StatementLineSubmission": { "additionalProperties": false, "description": "One normalised statement line.\n\n``currency`` is required and must equal the statement's commodity: the ledger declares currency, it never\ninfers it.", "properties": { "dt": { "description": "the line's value date (YYYY-MM-DD); must fall inside the declared period", "title": "Dt", "type": "string" }, "description": { "maxLength": 4096, "minLength": 1, "title": "Description", "type": "string" }, "amount": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Amount", "type": "string" }, "currency": { "maxLength": 64, "minLength": 1, "title": "Currency", "type": "string" }, "reference": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "the document's own reference for this line, when it has one", "title": "Reference" }, "raw": { "anyOf": [ { "maxLength": 8192, "type": "string" }, { "type": "null" } ], "description": "the line exactly as it appeared in the document, when that can be given", "title": "Raw" }, "source_key": { "anyOf": [ { "maxLength": 512, "type": "string" }, { "type": "null" } ], "description": "the line's stable identity in the document; derived when omitted", "title": "Source Key" } }, "required": [ "dt", "description", "amount", "currency" ], "title": "StatementLineSubmission", "type": "object" } }, "additionalProperties": false, "description": "Replace a statement loaded wrongly: the same subject, restated, pointing back at its predecessor.\n\nThe predecessor is kept and stays readable, because what was believed and when is part of the record. The\nreplacement is refused if the predecessor has already been replaced, if its period is locked, or if any of\nits lines is still booked. Undo those bookings first: a replacement must not silently orphan an entry it\ncaused.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "period_start": { "description": "first day of the statement period (YYYY-MM-DD)", "title": "Period Start", "type": "string" }, "period_end": { "description": "last day of the statement period; inclusive, and free to cross a year", "title": "Period End", "type": "string" }, "opening": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Opening", "type": "string" }, "closing": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Closing", "type": "string" }, "lines": { "items": { "$ref": "#/$defs/StatementLineSubmission" }, "title": "Lines", "type": "array" }, "document": { "$ref": "#/$defs/StatementDocument" }, "locator": { "description": "where in the document the closing balance is printed", "maxLength": 512, "minLength": 1, "title": "Locator", "type": "string" }, "page": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "description": "page of the document the closing balance is on", "title": "Page" }, "reason": { "description": "why this statement is being loaded; kept in the record", "minLength": 1, "title": "Reason", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied statement id; generated when omitted", "title": "Id" } }, "required": [ "account", "commodity", "period_start", "period_end", "opening", "closing", "document", "locator", "reason" ], "title": "StatementReplacementSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/statements/{statement_id}": { "get": { "tags": [ "statements" ], "summary": "One loaded statement: its period, its balances, its document and its replacement chain", "operationId": "get_statement_v1_entities__entity_id__statements__statement_id__get", "parameters": [ { "name": "statement_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Statement Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/statements/{statement_id}/lines": { "get": { "tags": [ "statements" ], "summary": "The lines of one statement, in document order", "operationId": "list_statement_lines_v1_entities__entity_id__statements__statement_id__lines_get", "parameters": [ { "name": "statement_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Statement Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementLinePage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/provenance": { "get": { "tags": [ "statements" ], "summary": "Where did this come from? Trace a statement line, a posting or an entry back to its document", "operationId": "get_provenance_v1_entities__entity_id__provenance_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "line_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "a statement line", "title": "Line Id" }, "description": "a statement line" }, { "name": "posting_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "one leg of an entry", "title": "Posting Id" }, "description": "one leg of an entry" }, { "name": "entry_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "a whole entry", "title": "Entry Id" }, "description": "a whole entry" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Provenance" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/lines": { "get": { "tags": [ "lines" ], "summary": "Statement lines across every statement, by date: what each is and what it was booked to", "description": "List lines across every statement over a date range, with what became of each and its entries.\n\n``GET /statements/{id}/lines`` reads one document in printed order. This reads by time: every line of every\nstatement in the range, ordered by date and then document order, the way somebody reviewing a period reads\nit.\n\n``state`` is applied after the page is read, because a line's status is not a column. It is derived from\nthe chain of explanations written for the line, their allocations, the entries behind them and whether the\nline's statement has been replaced. Doing that in SQL would be a second implementation of\n``lines_repo.line_state`` that could disagree with the first, which is worse than a short page.\n\nSo a page here can hold fewer items than ``limit``, or none, while ``next_cursor`` is still set.\n``filtered_after_page`` lists the filters applied after selection; while it is non-empty, a short page is\nnot the end of the results. Read until ``next_cursor`` is null.", "operationId": "list_lines_v1_entities__entity_id__lines_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive line date (YYYY-MM-DD)", "title": "From" }, "description": "inclusive line date (YYYY-MM-DD)" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive line date (YYYY-MM-DD)", "title": "To" }, "description": "inclusive line date (YYYY-MM-DD)" }, { "name": "account_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id" } }, { "name": "statement_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Id" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "keep only these line statuses; repeat for several", "title": "State" }, "description": "keep only these line statuses; repeat for several" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinePage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/lines/{line_id}": { "get": { "tags": [ "lines" ], "summary": "One statement line: its live explanation, its whole history and what of it is unexplained", "operationId": "get_line_v1_entities__entity_id__lines__line_id__get", "parameters": [ { "name": "line_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Line Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/lines/{line_id}/book": { "post": { "tags": [ "lines" ], "summary": "Post the entry this line is, and hold the line against it", "operationId": "book_line", "parameters": [ { "name": "line_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Line Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "LineLeg": { "additionalProperties": false, "description": "One contra leg of a booking: what the line was for.\n\nThe cash leg is not supplied and cannot be: it is the statement line itself, on the line's own account for\nthe line's own amount. These legs are the other side, and must sum to the negative of the line.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "amount": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Amount", "type": "string" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "required": [ "account", "commodity", "amount" ], "title": "LineLeg", "type": "object" } }, "additionalProperties": false, "description": "Post the entry this line is, and hold the line against the cash posting it creates, in one call.\n\nThe entry goes through the ordinary posting path with all its checks, and is posted, not drafted: since\nissue 0003 there is no two-step approval, and a booked line is in the books immediately. To change it\nlater, use ``reexplain``, which reverses or corrects it.", "properties": { "legs": { "description": "the contra side; sums to minus the line's amount", "items": { "$ref": "#/$defs/LineLeg" }, "minItems": 1, "title": "Legs", "type": "array" }, "narration": { "maxLength": 4096, "minLength": 1, "title": "Narration", "type": "string" }, "reason": { "description": "why this is what the line is; kept in the record", "minLength": 1, "title": "Reason", "type": "string" }, "dt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "entry date; defaults to the line's own date", "title": "Dt" }, "origin": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "entries.origin; defaults to 'source'", "title": "Origin" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "description": "memo on the cash leg", "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "tax code on the cash leg", "title": "Tax Code" }, "code": { "default": "", "description": "hledger transaction code", "maxLength": 255, "title": "Code", "type": "string" }, "comment": { "default": "", "maxLength": 4096, "title": "Comment", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied entry id; generated when omitted", "title": "Id" } }, "required": [ "legs", "narration", "reason" ], "title": "LineBookSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/lines/{line_id}/link": { "post": { "tags": [ "lines" ], "summary": "Say which existing posting(s) this line is, and for how much; posts nothing", "operationId": "link_line", "parameters": [ { "name": "line_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Line Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "LinePartSubmission": { "additionalProperties": false, "description": "One part of a split: an existing posting, and how much of the line it is.\n\nA posting is named by id: it has no path, and naming its account would not say which leg. The amount is in\nthe line's own commodity, the only commodity a part can be in.", "properties": { "posting_id": { "maxLength": 255, "minLength": 1, "title": "Posting Id", "type": "string" }, "amount": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Amount", "type": "string" } }, "required": [ "posting_id", "amount" ], "title": "LinePartSubmission", "type": "object" } }, "additionalProperties": false, "description": "Say which existing posting(s) this line is, and for how much. This posts nothing.\n\nSeveral parts make a split: one line explained by two or more postings. A sum short of the line's amount is\na partial allocation, a real state that the line reports and the close refuses until it is completed.", "properties": { "parts": { "items": { "$ref": "#/$defs/LinePartSubmission" }, "minItems": 1, "title": "Parts", "type": "array" }, "reason": { "minLength": 1, "title": "Reason", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied explanation id; generated when omitted", "title": "Id" } }, "required": [ "parts", "reason" ], "title": "LineLinkSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/lines/{line_id}/ignore": { "post": { "tags": [ "lines" ], "summary": "Record that this line will not be booked, and why", "operationId": "ignore_line", "parameters": [ { "name": "line_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Line Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Record that this line will not be booked, and why.\n\nAn ignored line counts as explained, and the close checks take it as answered. That is why the reason is\nrequired: it is the whole content of the decision a reviewer reads later.", "properties": { "reason": { "minLength": 1, "title": "Reason", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied explanation id; generated when omitted", "title": "Id" } }, "required": [ "reason" ], "title": "LineIgnoreSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/lines/{line_id}/reexplain": { "post": { "tags": [ "lines" ], "summary": "Supersede what was said about this line, correcting or reversing what it booked", "operationId": "reexplain_line", "parameters": [ { "name": "line_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Line Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LineResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$defs": { "LineLeg": { "additionalProperties": false, "description": "One contra leg of a booking: what the line was for.\n\nThe cash leg is not supplied and cannot be: it is the statement line itself, on the line's own account for\nthe line's own amount. These legs are the other side, and must sum to the negative of the line.", "properties": { "account": { "description": "account path (preferred) or stable account id", "maxLength": 255, "minLength": 1, "title": "Account", "type": "string" }, "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "amount": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Amount", "type": "string" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "required": [ "account", "commodity", "amount" ], "title": "LineLeg", "type": "object" }, "LinePartSubmission": { "additionalProperties": false, "description": "One part of a split: an existing posting, and how much of the line it is.\n\nA posting is named by id: it has no path, and naming its account would not say which leg. The amount is in\nthe line's own commodity, the only commodity a part can be in.", "properties": { "posting_id": { "maxLength": 255, "minLength": 1, "title": "Posting Id", "type": "string" }, "amount": { "description": "Signed decimal amount in whole commodity units, as a string; never a JSON number. Converted by the commodity's declared precision, so more decimal places than the currency has is refused rather than rounded.", "examples": [ "-12.00" ], "pattern": "^-?[0-9]+(\\.[0-9]+)?$", "title": "Amount", "type": "string" } }, "required": [ "posting_id", "amount" ], "title": "LinePartSubmission", "type": "object" } }, "additionalProperties": false, "description": "Supersede what was said about this line before.\n\nThe previous explanation is kept and the new one names it. If the previous one booked an entry, the books\nare put right through the ordinary correction path in the same transaction: ``kind: booked`` with new legs\ncorrects it, and ``kind: linked``/``ignored`` reverses it. A closed period refuses.", "properties": { "kind": { "description": "booked | linked | ignored", "title": "Kind", "type": "string" }, "reason": { "description": "why the previous reading was wrong; recorded verbatim", "minLength": 1, "title": "Reason", "type": "string" }, "legs": { "anyOf": [ { "items": { "$ref": "#/$defs/LineLeg" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "required for kind=booked", "title": "Legs" }, "parts": { "anyOf": [ { "items": { "$ref": "#/$defs/LinePartSubmission" }, "minItems": 1, "type": "array" }, { "type": "null" } ], "description": "required for kind=linked", "title": "Parts" }, "narration": { "anyOf": [ { "maxLength": 4096, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Narration" }, "dt": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Dt" }, "memo": { "anyOf": [ { "maxLength": 4096, "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Tax Code" }, "code": { "default": "", "maxLength": 255, "title": "Code", "type": "string" }, "comment": { "default": "", "maxLength": 4096, "title": "Comment", "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "caller-supplied explanation id; generated when omitted", "title": "Id" } }, "required": [ "kind", "reason" ], "title": "LineReexplainSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/documents": { "post": { "tags": [ "documents" ], "summary": "Register a document by its hash: an invoice, a receipt, a contract, anything the books rest on", "description": "Register a document; 201 when this call registered it, 200 when the same bytes were already here.\n\nA document is identified by its content, so two entries resting on one invoice will register it twice in the\nordinary course of events. That is not refused, and the caller does not need to look first. The one\ncontradiction that is refused is a different ``size_bytes`` for the same hash.", "operationId": "register_document", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } }, "description": "OK" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "A document to register: the bytes' hash, what the file is called, and where it is kept.\n\nThe ledger records this and does not fetch it, the same contract as ``POST /statements``. Identity is\n``sha256`` alone, so registering the same file twice returns the existing row rather than creating a second\none or refusing.", "properties": { "sha256": { "description": "SHA-256 of the document, 64 lowercase hex characters; its identity here", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "title": "Sha256", "type": "string" }, "filename": { "maxLength": 512, "minLength": 1, "title": "Filename", "type": "string" }, "media_type": { "maxLength": 255, "minLength": 1, "title": "Media Type", "type": "string" }, "size_bytes": { "description": "size of the document in bytes", "minimum": 0, "title": "Size Bytes", "type": "integer" }, "blob_path": { "default": "", "description": "where the bytes are kept, when this service keeps them", "maxLength": 2048, "title": "Blob Path", "type": "string" }, "external_ref": { "anyOf": [ { "maxLength": 2048, "type": "string" }, { "type": "null" } ], "description": "a reference to bytes held elsewhere, when we hold none", "title": "External Ref" }, "reason": { "description": "why it is being registered; kept in the record", "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "sha256", "filename", "media_type", "size_bytes", "reason" ], "title": "DocumentSubmission", "type": "object" } } } } }, "get": { "tags": [ "documents" ], "summary": "Registered documents, newest listing order, optionally by hash", "operationId": "list_documents_v1_entities__entity_id__documents_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "sha256", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "exact content hash, to ask whether a file is here", "title": "Sha256" }, "description": "exact content hash, to ask whether a file is here" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/documents": { "post": { "tags": [ "documents" ], "summary": "File a document against an entry: what this booking rests on, and where in the file it says so", "description": "File a registered document against an entry, so \"treatment follows the document\" can be checked.\n\nAn entry booked gross because no deductible document existed, and one booked net because a full invoice\ndid, differ by the document, so the document has to be reachable from the entry. It is linked through the\nsame ``evidence_links`` chain the statement loader uses, and ``GET /provenance?entry_id=`` reads it back.\n\nA closed period does not refuse this. A late invoice for a closed month is ordinary, and filing it changes\nnothing that month reports (migration 0004).", "operationId": "file_document", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntryFilingResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "File an already-registered document against an entry.\n\n``locator`` is where in the document the relevant part is; ``caption`` is what it is. A closed period does\nnot refuse this: an evidence link has no amount and no date of its own, so filing a late invoice against a\nclosed month's entry changes nothing that month reports.", "properties": { "document_id": { "description": "a document from POST /documents", "maxLength": 255, "minLength": 1, "title": "Document Id", "type": "string" }, "locator": { "description": "where in the document the relevant part is", "maxLength": 512, "minLength": 1, "title": "Locator", "type": "string" }, "caption": { "description": "what this document is, in a sentence", "maxLength": 1024, "minLength": 1, "title": "Caption", "type": "string" }, "page": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "title": "Page" }, "reason": { "description": "why it belongs on this entry; kept in the record", "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "document_id", "locator", "caption", "reason" ], "title": "DocumentFilingSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/documents/{document_id}": { "get": { "tags": [ "documents" ], "summary": "One document and every record that cites it", "operationId": "get_document_v1_entities__entity_id__documents__document_id__get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/documents/{document_id}/content": { "get": { "tags": [ "documents" ], "summary": "The document itself: the bytes this booking rests on, verified against their hash", "description": "Return the document's bytes, verified against the registered hash (issue 0007, acceptance criterion 3).\n\nThe bytes come only from under the configured ``blob_root``; a ``blob_path`` is caller-supplied, so without\nthat containment it would be a file-read primitive. They are hashed before any byte is returned, and\n``inline`` is honoured only for media types that cannot execute. A refusal never names a filesystem path,\nnot even when the file is simply missing.\n\nThere is no finer authorization than the entity scoping every route already has. Haddon records authority\nand does not enforce it (``decisions.md``, \"Authorisation\"). A credential reaches this route only for an\nentity it is scoped to, and an id from another entity's file is a plain 404 like any other.", "operationId": "document_content_v1_entities__entity_id__documents__document_id__content_get", "parameters": [ { "name": "document_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Document Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "disposition", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(attachment|inline)$", "description": "inline is honoured only for media types that cannot execute; everything else downloads", "default": "attachment", "title": "Disposition" }, "description": "inline is honoured only for media types that cannot execute; everything else downloads" } ], "responses": { "200": { "description": "the registered bytes, verified against the registered hash", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/awaiting-document": { "post": { "tags": [ "provisional" ], "summary": "Record that this booking is provisional, naming the document that would settle it", "description": "Mark a posted booking as resting on an assumption that an awaited document may overturn.\n\nThe booking stands. This is not a draft and not a doubt about the amount: the entry stays posted and counts\nin every report, because a cost belongs in the month it happened, at the best figure available. Calling this\nagain for the same entry restates the expectation. Filing the awaited document against the entry\n(``POST /entries/{id}/documents``) settles it.", "operationId": "await_document", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpectationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Record that a booking is provisional: it stands, and a named document is expected that may change it.\n\n``awaiting`` is required because what is expected is the whole content of the state: \"this is provisional\"\nwithout saying what would settle it helps nobody. Submitting again for an entry already awaiting something\nrestates the expectation rather than opening a second one.", "properties": { "awaiting": { "description": "the document that would settle this, in a phrase", "maxLength": 1024, "minLength": 1, "title": "Awaiting", "type": "string" }, "reason": { "description": "why it was booked this way meanwhile; kept in the record", "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "awaiting", "reason" ], "title": "ExpectationSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/awaiting-document/withdraw": { "post": { "tags": [ "provisional" ], "summary": "No document is coming: the booking stands as it is, and the reason says why", "description": "Close an expectation because no document is coming; the booking stands as it is.\n\nThis is kept separate from a document arriving. A simplified receipt the supplier will never reissue settles\nthe question, but not the way an invoice would, and the record keeps the two apart so the reason each item\nleft the provisional list stays true.", "operationId": "withdraw_expectation", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpectationResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "No document is coming. The booking stands as it is, and the reason says why it is no longer provisional.\n\nThis is deliberately a different act from the document arriving. A receipt that will never be reissued is a\ndifferent fact about the books from an invoice that turned up, and the record keeps them apart.", "properties": { "reason": { "description": "why no document is expected any more", "minLength": 1, "title": "Reason", "type": "string" } }, "required": [ "reason" ], "title": "WithdrawalSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/provisional": { "get": { "tags": [ "provisional" ], "summary": "What in these books is provisional: every booking still awaiting a document", "description": "List every booking still awaiting a document, with its entry.\n\nOrdered by when the expectation was recorded, not by entry date, because the list is worked through as open\nitems. The ``from``/``to`` filters apply to the entry date, so a month's page can ask what is provisional in\nthat month while everything older and still open remains reachable.", "operationId": "list_provisional_v1_entities__entity_id__provisional_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive, on the entry date", "title": "From" }, "description": "inclusive, on the entry date" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive, on the entry date", "title": "To" }, "description": "inclusive, on the entry date" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionalPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/entries/{entry_id}/unrecovered-tax": { "post": { "tags": [ "unrecovered tax" ], "summary": "Record recoverable tax that was not recovered on this entry, and why", "description": "Record the decision to book a cost gross of a recoverable tax, and the reason for it.\n\nSuch a decision has a reason: the document does not support a claim, or there is no document. The gross\nfigure records only the consequence, which is how an amount ends up inside a fixed asset with nobody able to\nsay why. Nothing is posted here; the arithmetic already happened.", "operationId": "record_unrecovered_tax", "parameters": [ { "name": "entry_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Entry Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnrecoveredResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "An amount of recoverable tax that was not recovered on this entry, and why.\n\nNothing about a country or a tax is modelled. ``recoverable_until`` is a date the caller supplies; the\nledger applies no regime rule. It is what makes \"what can we still reclaim, and by when\" answerable.\n``tax_code`` is the entity's own code, the same column name the chart and the postings use.", "properties": { "commodity": { "maxLength": 64, "minLength": 1, "title": "Commodity", "type": "string" }, "amount_micros": { "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ], "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "type": "string" }, "reason": { "description": "why it was not recovered; the whole point of the record", "minLength": 1, "title": "Reason", "type": "string" }, "posting_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "the leg the amount is sitting inside, when it is known", "title": "Posting Id" }, "tax_code": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "which tax, in the entity's own code", "title": "Tax Code" }, "recoverable_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "the last date it could still be recovered (YYYY-MM-DD), when a rule sets one", "title": "Recoverable Until" } }, "required": [ "commodity", "amount_micros", "reason" ], "title": "UnrecoveredSubmission", "type": "object" } } } } } }, "/v1/entities/{entity_id}/unrecovered-tax/{record_id}/resolve": { "post": { "tags": [ "unrecovered tax" ], "summary": "Close it: recovered after all, naming the entry that did it, or deliberately forgone", "description": "Close a record as ``recovered`` (naming the recovering entry) or ``forgone`` (the reason stands alone).\n\nWithout ``forgone`` the list would only grow. When a claim window closes, or an amount is not worth the\npaperwork, the record would otherwise go on saying money is recoverable when it is not.", "operationId": "resolve_unrecovered_tax", "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Record Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnrecoveredResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "additionalProperties": false, "description": "Close a record.\n\n``recovered`` names the entry that recovered it. ``forgone`` names nothing, so its reason has to explain it\n(the window closed, or the claim was not worth making).", "properties": { "outcome": { "description": "recovered | forgone", "title": "Outcome", "type": "string" }, "reason": { "minLength": 1, "title": "Reason", "type": "string" }, "recovered_entry_id": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "description": "required when recovered; a different entry, because a recovery is its own event", "title": "Recovered Entry Id" } }, "required": [ "outcome", "reason" ], "title": "UnrecoveredResolution", "type": "object" } } } } } }, "/v1/entities/{entity_id}/unrecovered-tax": { "get": { "tags": [ "unrecovered tax" ], "summary": "What tax are we not reclaiming, and why: with a total per commodity", "description": "List unrecovered-tax records in one state, with a total per commodity. Defaults to ``unrecovered``.\n\n``totals`` is per commodity and never summed across commodities: two currencies are two answers. The\n``from``/``to`` filters apply to the entry date.", "operationId": "list_unrecovered_v1_entities__entity_id__unrecovered_tax_get", "parameters": [ { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "description": "unrecovered | recovered | forgone", "default": "unrecovered", "title": "State" }, "description": "unrecovered | recovered | forgone" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive, on the entry date", "title": "From" }, "description": "inclusive, on the entry date" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "inclusive, on the entry date", "title": "To" }, "description": "inclusive, on the entry date" }, { "name": "limit", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Limit" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cursor" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnrecoveredPage" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } }, "/v1/entities/{entity_id}/unrecovered-tax/{record_id}": { "get": { "tags": [ "unrecovered tax" ], "summary": "One record and the whole history of the entry it is about", "operationId": "get_record_v1_entities__entity_id__unrecovered_tax__record_id__get", "parameters": [ { "name": "record_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Record Id" } }, { "name": "entity_id", "in": "path", "required": true, "schema": { "type": "string", "description": "The entity this path is relative to", "title": "Entity Id" }, "description": "The entity this path is relative to" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnrecoveredResponse" } } } }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Bad Request" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Forbidden" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Not Found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Conflict" }, "412": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Precondition Failed" }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Unprocessable Content" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Internal Server Error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } }, "description": "Service Unavailable" } } } } }, "components": { "schemas": { "Account": { "properties": { "id": { "type": "string", "title": "Id" }, "path": { "type": "string", "title": "Path" }, "type": { "type": "string", "title": "Type" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Code" }, "tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Code" }, "is_cash": { "type": "boolean", "title": "Is Cash" }, "archived": { "type": "boolean", "title": "Archived" }, "version": { "type": "integer", "title": "Version" }, "commodities": { "items": { "type": "string" }, "type": "array", "title": "Commodities" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "id", "path", "type", "code", "tax_code", "is_cash", "archived", "version", "commodities", "links" ], "title": "Account" }, "AccountPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/Account" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor" ], "title": "AccountPage" }, "AccountResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "account": { "$ref": "#/components/schemas/Account" }, "version": { "type": "integer", "title": "Version" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "account", "version" ], "title": "AccountResponse" }, "BalanceCheck": { "properties": { "date": { "type": "string", "title": "Date" }, "difference_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Difference Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] } }, "additionalProperties": false, "type": "object", "required": [ "date", "difference_micros" ], "title": "BalanceCheck" }, "BalanceSheet": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "report": { "type": "string", "title": "Report" }, "through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Through" }, "sections": { "additionalProperties": { "items": { "$ref": "#/components/schemas/ReportLine" }, "type": "array" }, "type": "object", "title": "Sections" }, "totals": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Totals" }, "result_micros": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Result Micros" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "report", "through", "sections", "totals", "result_micros", "links" ], "title": "BalanceSheet" }, "BalanceSheetView": { "properties": { "commodity": { "type": "string", "title": "Commodity" }, "as_of": { "type": "string", "title": "As Of" }, "comparative_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparative As Of" }, "sections": { "items": { "$ref": "#/components/schemas/ShapedSection" }, "type": "array", "title": "Sections" }, "total_assets_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Total Assets Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "total_funding_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Total Funding Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "difference_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Difference Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "comparative_total_assets_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Total Assets Micros" }, "comparative_total_funding_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Total Funding Micros" }, "comparative_difference_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Difference Micros" }, "checks": { "items": { "$ref": "#/components/schemas/BalanceCheck" }, "type": "array", "title": "Checks", "description": "one entry per column shown: assets less the two sides funding them, which is zero on a balanced journal at every date" } }, "additionalProperties": false, "type": "object", "required": [ "commodity", "as_of", "comparative_as_of", "sections", "total_assets_micros", "total_funding_micros", "difference_micros", "checks" ], "title": "BalanceSheetView" }, "BatchResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "operation_id": { "type": "string", "title": "Operation Id", "description": "the one operations row this batch was recorded as" }, "count": { "type": "integer", "title": "Count" }, "entry_ids": { "items": { "type": "string" }, "type": "array", "title": "Entry Ids", "description": "the entries that were posted, in submission order" }, "totals": { "items": { "$ref": "#/components/schemas/BatchTotal" }, "type": "array", "title": "Totals", "description": "what was actually posted; equal to the assertion, or this would have been refused" }, "audit_seq": { "type": "integer", "title": "Audit Seq", "description": "the batch.posted audit action's event sequence" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "operation_id", "count", "entry_ids", "totals", "audit_seq", "links" ], "title": "BatchResponse" }, "BatchTotal": { "properties": { "commodity": { "type": "string", "maxLength": 64, "minLength": 1, "title": "Commodity" }, "debits_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Debits Micros", "description": "sum of the positive postings of this commodity, in micros", "examples": [ "1200000" ] }, "credits_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Credits Micros", "description": "sum of the negative postings of this commodity, as a magnitude", "examples": [ "1200000" ] } }, "additionalProperties": false, "type": "object", "required": [ "commodity", "debits_micros", "credits_micros" ], "title": "BatchTotal", "description": "What the caller says one commodity comes to across the whole batch, as two magnitudes in micros.\n\nBoth are non-negative: ``debits_micros`` is the sum of every positive posting of this commodity and\n``credits_micros`` of every negative one. Each entry balances, so the two must be equal once the batch is\nbuilt, and that is why both are asked for. The caller computes them from its own source, so a figure\ntransposed on one side of the conversion disagrees with the other and the batch is refused." }, "Capabilities": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "actor_recorded_as": { "type": "string", "title": "Actor Recorded As" }, "entities_in_scope": { "items": { "type": "string" }, "type": "array", "title": "Entities In Scope" }, "reads": { "items": { "type": "string" }, "type": "array", "title": "Reads" }, "writes": { "items": { "type": "string" }, "type": "array", "title": "Writes" }, "commands": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Commands", "description": "the named write commands this installation serves: the command's name, its verb and its path. The name is the same string as the OpenAPI operationId and the application handler" }, "service_reads": { "items": { "type": "string" }, "type": "array", "title": "Service Reads", "description": "the /v1 reads that are not relative to an entity, as absolute paths" }, "service_commands": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Service Commands", "description": "the named write commands that are not relative to an entity, as absolute paths. `initialize_entity` is here: a book has to exist before there is an entity to address" }, "limits": { "$ref": "#/components/schemas/Limits" }, "amount_contract": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Amount Contract" }, "commodities": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Commodities" }, "account_commodities": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Account Commodities" }, "idempotency": { "additionalProperties": true, "type": "object", "title": "Idempotency" }, "pagination": { "additionalProperties": true, "type": "object", "title": "Pagination" }, "dates": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Dates" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "actor_recorded_as", "entities_in_scope", "reads", "writes", "commands", "service_reads", "service_commands", "limits", "amount_contract", "commodities", "account_commodities", "idempotency", "pagination", "dates" ], "title": "Capabilities" }, "ChartChangeResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "account": { "$ref": "#/components/schemas/Account" }, "version": { "type": "integer", "title": "Version" }, "audit_seq": { "type": "integer", "title": "Audit Seq", "description": "the account.created / account.archived action's event sequence" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "account", "version", "audit_seq", "links" ], "title": "ChartChangeResponse", "description": "The reply to an account command: the account as it now stands, and its audit action." }, "Check": { "properties": { "name": { "type": "string", "title": "Name" }, "ok": { "type": "boolean", "title": "Ok" }, "detail": { "type": "string", "title": "Detail" } }, "additionalProperties": false, "type": "object", "required": [ "name", "ok", "detail" ], "title": "Check" }, "CloseCheck": { "properties": { "check": { "type": "string", "title": "Check" }, "title": { "type": "string", "title": "Title" }, "requirement": { "type": "string", "title": "Requirement" }, "status": { "type": "string", "title": "Status", "description": "pass | fail | unevaluable; only 'pass' is a positive answer" }, "reason": { "type": "string", "title": "Reason" }, "blocking": { "type": "boolean", "title": "Blocking" }, "outstanding": { "items": { "$ref": "#/components/schemas/CloseOutstanding" }, "type": "array", "title": "Outstanding" }, "outstanding_truncated": { "type": "integer", "title": "Outstanding Truncated" }, "waiver": { "anyOf": [ { "$ref": "#/components/schemas/CloseWaiver" }, { "type": "null" } ] } }, "additionalProperties": false, "type": "object", "required": [ "check", "title", "requirement", "status", "reason", "blocking", "outstanding", "outstanding_truncated", "waiver" ], "title": "CloseCheck" }, "CloseChecks": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "through": { "type": "string", "title": "Through" }, "window_start": { "type": "string", "title": "Window Start" }, "prior_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Through" }, "months": { "items": { "additionalProperties": { "type": "string" }, "type": "object" }, "type": "array", "title": "Months" }, "eligible": { "type": "boolean", "title": "Eligible", "description": "every check positively passed; a recorded override does NOT make this true" }, "may_close": { "type": "boolean", "title": "May Close", "description": "nothing blocks: every check passed or a recorded override waives it" }, "checks": { "items": { "$ref": "#/components/schemas/CloseCheck" }, "type": "array", "title": "Checks" }, "blocking_checks": { "items": { "type": "string" }, "type": "array", "title": "Blocking Checks" }, "unmatched_overrides": { "items": { "$ref": "#/components/schemas/CloseOverride" }, "type": "array", "title": "Unmatched Overrides", "description": "overrides that name no currently-blocking check; a close would refuse them" }, "lock": { "$ref": "#/components/schemas/PeriodLock", "description": "the period lock as this evaluation read it. Its `version` is the `expected_version` a close or reopen sends back, so the answer to 'would this close?' carries what performing it needs" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "through", "window_start", "prior_through", "months", "eligible", "may_close", "checks", "blocking_checks", "unmatched_overrides", "lock", "links" ], "title": "CloseChecks" }, "CloseOutstanding": { "properties": { "kind": { "type": "string", "title": "Kind" }, "message": { "type": "string", "title": "Message" }, "detail": { "additionalProperties": true, "type": "object", "title": "Detail" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "message", "detail" ], "title": "CloseOutstanding", "description": "One specific thing that would have to change for a check to pass.\n\nAmounts inside ``detail`` are integer micro strings, as everywhere else." }, "CloseOverride": { "properties": { "check": { "type": "string", "minLength": 1, "title": "Check", "description": "the check key this override answers, e.g. 'statement_coverage'" }, "reason": { "type": "string", "minLength": 1, "title": "Reason", "description": "why this period is being closed with that check unsatisfied" } }, "additionalProperties": false, "type": "object", "required": [ "check", "reason" ], "title": "CloseOverride", "description": "Close over one named blocking check: the check, and why. There is no id to pre-create and no wildcard.\n\nAn override is matched against the checks as the server has just evaluated them, so it can only name a\nfailure that is real at this moment. A blanket bypass cannot be expressed. Each override is stored on the\nclose record with the check's status and outstanding count as they stood, the acting principal and this\nreason." }, "ClosePeriodResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "close_id": { "type": "string", "title": "Close Id" }, "kind": { "type": "string", "title": "Kind" }, "lock": { "$ref": "#/components/schemas/PeriodLock" }, "snapshot": { "$ref": "#/components/schemas/CloseSnapshot" }, "checks": { "additionalProperties": true, "type": "object", "title": "Checks", "description": "the checks this close ran, exactly as GET /close-checks reports them" }, "audit_seq": { "type": "integer", "title": "Audit Seq" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "close_id", "kind", "lock", "snapshot", "checks", "audit_seq", "links" ], "title": "ClosePeriodResponse" }, "CloseRecord": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "id": { "type": "string", "title": "Id" }, "kind": { "type": "string", "title": "Kind" }, "through": { "type": "string", "title": "Through" }, "prior_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Through" }, "snapshot_id": { "type": "string", "title": "Snapshot Id" }, "reason": { "type": "string", "title": "Reason" }, "overrides": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Overrides", "description": "the waivers this close was let through on, each with the check, the actor and the reason; empty on a reopen, which waives nothing" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "id", "kind", "through", "prior_through", "snapshot_id", "reason", "overrides", "created_at", "created_by", "links" ], "title": "CloseRecord", "description": "One close or reopen, read back. ``links.snapshot`` is the immutable state it was recorded against." }, "CloseSnapshot": { "properties": { "id": { "type": "string", "title": "Id" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "state_hash": { "type": "string", "title": "State Hash" }, "through": { "type": "string", "title": "Through" } }, "additionalProperties": false, "type": "object", "required": [ "id", "snapshot_seq", "state_hash", "through" ], "title": "CloseSnapshot", "description": "The verification snapshot the close was recorded against. Computed by the server, never supplied." }, "CloseWaiver": { "properties": { "check": { "type": "string", "title": "Check" }, "through": { "type": "string", "title": "Through" }, "reason": { "type": "string", "title": "Reason" }, "actor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Actor", "description": "the principal that ran the close; null on a read-only preview" }, "status_at_close": { "type": "string", "title": "Status At Close" }, "reason_at_close": { "type": "string", "title": "Reason At Close" }, "outstanding_at_close": { "type": "integer", "title": "Outstanding At Close" } }, "additionalProperties": false, "type": "object", "required": [ "check", "through", "reason", "actor", "status_at_close", "reason_at_close", "outstanding_at_close" ], "title": "CloseWaiver", "description": "An override, matched to the check it let through and to what that check found at that moment." }, "CommodityStatements": { "properties": { "commodity": { "type": "string", "title": "Commodity" }, "income_statement": { "$ref": "#/components/schemas/IncomeStatementView" }, "balance_sheet": { "$ref": "#/components/schemas/BalanceSheetView" } }, "additionalProperties": false, "type": "object", "required": [ "commodity", "income_statement", "balance_sheet" ], "title": "CommodityStatements" }, "ComparativeLabel": { "properties": { "start": { "type": "string", "title": "Start" }, "end": { "type": "string", "title": "End" }, "name": { "type": "string", "title": "Name" } }, "additionalProperties": false, "type": "object", "required": [ "start", "end", "name" ], "title": "ComparativeLabel" }, "Composition": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "report": { "type": "string", "title": "Report" }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start" }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End" }, "origins": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Origins" }, "journals": { "additionalProperties": { "type": "integer" }, "type": "object", "title": "Journals" }, "entry_count": { "type": "integer", "title": "Entry Count" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "report", "start", "end", "origins", "journals", "entry_count", "links" ], "title": "Composition" }, "CorrectionLink": { "properties": { "id": { "type": "string", "title": "Id" }, "role": { "type": "string", "title": "Role", "description": "original | mirror | replacement \u2014 which end of this correction the entry is" }, "original_id": { "type": "string", "title": "Original Id" }, "mirror_id": { "type": "string", "title": "Mirror Id" }, "replacement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacement Id" }, "reason": { "type": "string", "title": "Reason" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "id", "role", "original_id", "mirror_id", "replacement_id", "reason", "created_at", "created_by", "links" ], "title": "CorrectionLink", "description": "One link in an entry's correction chain, and which end of it this entry is.\n\n``role`` saves a reader re-deriving the relationship from three ids: ``original`` means this entry was\ncorrected, ``mirror`` means it is the reversal, and ``replacement`` means it is what was posted in the\noriginal's place. A reversal with no restatement has no ``replacement_id``: \"the books stopped saying this\"\nrather than \"the books say it differently now\"." }, "Document": { "properties": { "sha256": { "type": "string", "title": "Sha256", "description": "SHA-256 of the registered bytes, and the document's identity" }, "filename": { "type": "string", "title": "Filename" }, "media_type": { "type": "string", "title": "Media Type" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "storage": { "type": "string", "title": "Storage", "description": "stored | external" }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Ref", "description": "where the bytes are, when this service does not hold them" }, "id": { "type": "string", "title": "Id" }, "filing_count": { "type": "integer", "title": "Filing Count", "description": "how many records cite this document" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "sha256", "filename", "media_type", "size_bytes", "storage", "external_ref", "id", "filing_count", "created_at", "created_by", "links" ], "title": "Document", "description": "A registered document, read back.\n\n``links.content`` is present only when the bytes are here to be served. An ``external`` document has\nnothing at that address, and the link would only give the interface a button that always fails." }, "DocumentFiling": { "properties": { "evidence_id": { "type": "string", "title": "Evidence Id" }, "subject_kind": { "type": "string", "title": "Subject Kind", "description": "entry | statement" }, "subject_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Subject Id" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "locator": { "type": "string", "title": "Locator" }, "caption": { "type": "string", "title": "Caption" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" } }, "additionalProperties": false, "type": "object", "required": [ "evidence_id", "subject_kind", "subject_id", "page", "locator", "caption", "created_at", "created_by" ], "title": "DocumentFiling", "description": "One place a document is cited: which record, where in the file, and what it says." }, "DocumentPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/Document" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor" ], "title": "DocumentPage" }, "DocumentResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "document": { "$ref": "#/components/schemas/Document" }, "created": { "type": "boolean", "title": "Created", "description": "false when this call found the document already registered" }, "filings": { "items": { "$ref": "#/components/schemas/DocumentFiling" }, "type": "array", "title": "Filings" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "document", "created", "filings" ], "title": "DocumentResponse" }, "DocumentView": { "properties": { "sha256": { "type": "string", "title": "Sha256", "description": "SHA-256 of the registered bytes, and the document's identity" }, "filename": { "type": "string", "title": "Filename" }, "media_type": { "type": "string", "title": "Media Type" }, "size_bytes": { "type": "integer", "title": "Size Bytes" }, "storage": { "type": "string", "title": "Storage", "description": "stored | external" }, "external_ref": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Ref", "description": "where the bytes are, when this service does not hold them" } }, "additionalProperties": false, "type": "object", "required": [ "sha256", "filename", "media_type", "size_bytes", "storage", "external_ref" ], "title": "DocumentView", "description": "The original document as a reader sees it: what identifies it, and whether it can be opened here.\n\nThere is deliberately no ``blob_path`` (removed in issue 0007): a server-local path is no use to a reviewer\nand discloses where the service keeps files. ``storage`` says instead whether the bytes are available:\n``stored`` means ``GET /documents/{id}/content`` will hand them over, ``external`` means only\n``external_ref`` exists and the document is held elsewhere." }, "EntityList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/EntitySummary" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "snapshot_seq": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Snapshot Seq" } }, "additionalProperties": false, "type": "object", "required": [ "items" ], "title": "EntityList" }, "EntitySummary": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "legal_form": { "type": "string", "title": "Legal Form" }, "country": { "type": "string", "title": "Country" }, "base_currency": { "type": "string", "title": "Base Currency" }, "commodities": { "items": { "type": "string" }, "type": "array", "title": "Commodities" }, "lock_through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lock Through" }, "lock_version": { "type": "integer", "title": "Lock Version" }, "lock_close_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lock Close Id", "description": "the close record that set the current lock; the way from 'this period is closed' to the snapshot it was closed against, without walking /events" }, "live_close_eligible": { "type": "boolean", "title": "Live Close Eligible" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "legal_form", "country", "base_currency", "commodities", "lock_through", "lock_version", "lock_close_id", "live_close_eligible", "links" ], "title": "EntitySummary" }, "Entry": { "properties": { "id": { "type": "string", "title": "Id" }, "dt": { "type": "string", "title": "Dt" }, "narration": { "type": "string", "title": "Narration" }, "status": { "type": "string", "title": "Status" }, "origin": { "type": "string", "title": "Origin" }, "version": { "type": "integer", "title": "Version" }, "code": { "type": "string", "title": "Code" }, "comment": { "type": "string", "title": "Comment" }, "tags": { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array", "title": "Tags" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "postings": { "items": { "$ref": "#/components/schemas/Posting" }, "type": "array", "title": "Postings" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "id", "dt", "narration", "status", "origin", "version", "code", "comment", "tags", "created_at", "created_by", "postings", "links" ], "title": "Entry" }, "EntryCorrection": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "correction_id": { "type": "string", "title": "Correction Id" }, "original_id": { "type": "string", "title": "Original Id" }, "mirror_id": { "type": "string", "title": "Mirror Id" }, "replacement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacement Id" }, "audit_seq": { "type": "integer", "title": "Audit Seq", "description": "the entry.corrected audit action's event sequence" }, "entry": { "$ref": "#/components/schemas/Entry", "description": "the mirror that was posted" }, "replacement": { "$ref": "#/components/schemas/Entry", "description": "the entry that now stands in the original's place" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "correction_id", "original_id", "mirror_id", "replacement_id", "audit_seq", "entry", "replacement", "links" ], "title": "EntryCorrection" }, "EntryEvents": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "entry_id": { "type": "string", "title": "Entry Id" }, "items": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array", "title": "Items" }, "since": { "type": "integer", "title": "Since" }, "next_since": { "type": "integer", "title": "Next Since" }, "high_water": { "type": "integer", "title": "High Water" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "entry_id", "items", "since", "next_since", "high_water" ], "title": "EntryEvents" }, "EntryFiling": { "properties": { "id": { "type": "string", "title": "Id" }, "entry_id": { "type": "string", "title": "Entry Id" }, "document_id": { "type": "string", "title": "Document Id" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "locator": { "type": "string", "title": "Locator" }, "caption": { "type": "string", "title": "Caption" }, "document": { "additionalProperties": true, "type": "object", "title": "Document" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "met_expectation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Met Expectation Id", "description": "the provisional booking this filing settled, when the entry was awaiting one" } }, "additionalProperties": false, "type": "object", "required": [ "id", "entry_id", "document_id", "page", "locator", "caption", "document", "created_at", "created_by" ], "title": "EntryFiling" }, "EntryFilingResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "filing": { "$ref": "#/components/schemas/EntryFiling" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "filing", "links" ], "title": "EntryFilingResponse" }, "EntryPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/Entry" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor" ], "title": "EntryPage" }, "EntryResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "entry": { "$ref": "#/components/schemas/Entry" }, "version": { "type": "integer", "title": "Version" }, "reversed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reversed By", "description": "the mirror that reverses this entry, when one has been posted; a posted entry that already has one cannot be reversed again" }, "corrections": { "items": { "$ref": "#/components/schemas/CorrectionLink" }, "type": "array", "title": "Corrections", "description": "every correction this entry is part of, whichever end of it it is; issue 0007" }, "state": { "type": "string", "title": "State", "description": "posted | corrected | reversed | draft | void \u2014 what this entry is now" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "entry", "version", "reversed_by", "corrections", "state" ], "title": "EntryResponse" }, "EntryReversal": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "correction_id": { "type": "string", "title": "Correction Id" }, "original_id": { "type": "string", "title": "Original Id" }, "mirror_id": { "type": "string", "title": "Mirror Id" }, "replacement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replacement Id" }, "audit_seq": { "type": "integer", "title": "Audit Seq", "description": "the entry.reversed audit action's event sequence" }, "entry": { "$ref": "#/components/schemas/Entry", "description": "the mirror that was posted" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "correction_id", "original_id", "mirror_id", "replacement_id", "audit_seq", "entry", "links" ], "title": "EntryReversal" }, "ErrorBody": { "properties": { "code": { "type": "string", "title": "Code" }, "message": { "type": "string", "title": "Message" }, "retryable": { "type": "boolean", "title": "Retryable" }, "details": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Details" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "next_action": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Next Action" } }, "additionalProperties": false, "type": "object", "required": [ "code", "message", "retryable", "details" ], "title": "ErrorBody" }, "ErrorEnvelope": { "properties": { "error": { "$ref": "#/components/schemas/ErrorBody" } }, "additionalProperties": false, "type": "object", "required": [ "error" ], "title": "ErrorEnvelope" }, "Event": { "properties": { "seq": { "type": "integer", "title": "Seq" }, "kind": { "type": "string", "title": "Kind" }, "subject_kind": { "type": "string", "title": "Subject Kind" }, "subject_id": { "type": "string", "title": "Subject Id" }, "before": { "title": "Before" }, "after": { "title": "After" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "request_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Request Id" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" } }, "additionalProperties": false, "type": "object", "required": [ "seq", "kind", "subject_kind", "subject_id", "before", "after", "reason", "request_id", "created_at", "created_by" ], "title": "Event" }, "EventPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/Event" }, "type": "array", "title": "Items" }, "since": { "type": "integer", "title": "Since" }, "next_since": { "type": "integer", "title": "Next Since" }, "high_water": { "type": "integer", "title": "High Water" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "since", "next_since", "high_water" ], "title": "EventPage" }, "Expectation": { "properties": { "id": { "type": "string", "title": "Id" }, "entry_id": { "type": "string", "title": "Entry Id" }, "state": { "type": "string", "title": "State", "description": "awaiting | met | withdrawn" }, "awaiting": { "type": "string", "title": "Awaiting" }, "reason": { "type": "string", "title": "Reason" }, "evidence_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Evidence Id", "description": "the filed document that met it, when it was met" }, "supersedes_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supersedes Id" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" } }, "additionalProperties": false, "type": "object", "required": [ "id", "entry_id", "state", "awaiting", "reason", "supersedes_id", "created_at", "created_by" ], "title": "Expectation" }, "ExpectationResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "expectation": { "$ref": "#/components/schemas/Expectation" }, "history": { "items": { "$ref": "#/components/schemas/Expectation" }, "type": "array", "title": "History", "description": "every record about this entry, oldest first" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "expectation", "history", "links" ], "title": "ExpectationResponse" }, "Export": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "id": { "type": "string", "title": "Id" }, "snapshot_id": { "type": "string", "title": "Snapshot Id" }, "operation_id": { "type": "string", "title": "Operation Id" }, "manifest_sha256": { "type": "string", "title": "Manifest Sha256" }, "artifacts": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Artifacts" }, "verifier": { "additionalProperties": true, "type": "object", "title": "Verifier" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "id", "snapshot_id", "operation_id", "manifest_sha256", "artifacts", "verifier", "created_at", "created_by", "links" ], "title": "Export" }, "ExportArtifact": { "properties": { "path": { "type": "string", "title": "Path", "description": "the file name, relative to this export's ledger directory" }, "sha256": { "type": "string", "title": "Sha256" }, "bytes": { "type": "integer", "title": "Bytes" }, "href": { "type": "string", "title": "Href", "description": "where these bytes are served from" } }, "additionalProperties": false, "type": "object", "required": [ "path", "sha256", "bytes", "href" ], "title": "ExportArtifact", "description": "One published file: its name in the ledger directory, its digest and its length.\n\nThe same three fields the ``exports`` row stores, plus where to fetch it. The digest is the integrity\nclaim that these are the bytes ``hledger check --strict`` passed under the pinned binary, and the download\nre-hashes the file against it rather than trusting the directory." }, "ExportRun": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "export_id": { "type": "string", "title": "Export Id" }, "snapshot_id": { "type": "string", "title": "Snapshot Id" }, "operation_id": { "type": "string", "title": "Operation Id" }, "state_hash": { "type": "string", "title": "State Hash", "description": "the digest of everything rendered; one state is one snapshot" }, "manifest_sha256": { "type": "string", "title": "Manifest Sha256" }, "range_start": { "type": "string", "title": "Range Start", "description": "the inclusive first day actually covered (YYYY-MM-DD)" }, "range_end": { "type": "string", "title": "Range End", "description": "the inclusive last day actually covered (YYYY-MM-DD)" }, "ledger_dir": { "type": "string", "title": "Ledger Dir", "description": "the directory the files were published into, relative to this entity's export root" }, "artifacts": { "items": { "$ref": "#/components/schemas/ExportArtifact" }, "type": "array", "title": "Artifacts" }, "counts": { "additionalProperties": true, "type": "object", "title": "Counts", "description": "files, entries, postings, accounts, commodities and the source groups the range covers" }, "verifier": { "additionalProperties": true, "type": "object", "title": "Verifier", "description": "the pinned hledger build that checked the output, and its verdict" }, "event_seq": { "type": "integer", "title": "Event Seq", "description": "the export.completed event's sequence" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "export_id", "snapshot_id", "operation_id", "state_hash", "manifest_sha256", "range_start", "range_end", "ledger_dir", "artifacts", "counts", "verifier", "event_seq", "links" ], "title": "ExportRun", "description": "What one export wrote: the immutable row, the state it was rendered from, and the files themselves." }, "Health": { "properties": { "status": { "type": "string", "title": "Status" }, "service": { "type": "string", "title": "Service" }, "api_version": { "type": "string", "title": "Api Version" } }, "additionalProperties": false, "type": "object", "required": [ "status", "service", "api_version" ], "title": "Health" }, "IncomeStatement": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "report": { "type": "string", "title": "Report" }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start" }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End" }, "lines": { "items": { "$ref": "#/components/schemas/ReportLine" }, "type": "array", "title": "Lines" }, "net_micros": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Net Micros" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "report", "start", "end", "lines", "net_micros", "links" ], "title": "IncomeStatement" }, "IncomeStatementView": { "properties": { "commodity": { "type": "string", "title": "Commodity" }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start" }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End" }, "comparative_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparative Start" }, "comparative_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Comparative End" }, "result_label": { "type": "string", "title": "Result Label", "description": "this commodity's own bottom line, said rather than left to the sign; a document of several commodities has one label per commodity" }, "sections": { "items": { "$ref": "#/components/schemas/ShapedSection" }, "type": "array", "title": "Sections" }, "result_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Result Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "comparative_result_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Result Micros" } }, "additionalProperties": false, "type": "object", "required": [ "commodity", "start", "end", "comparative_start", "comparative_end", "result_label", "sections", "result_micros" ], "title": "IncomeStatementView" }, "JournalEntryResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "entry": { "$ref": "#/components/schemas/Entry" }, "version": { "type": "integer", "title": "Version" }, "audit_seq": { "type": "integer", "title": "Audit Seq", "description": "the entry.posted audit action's event sequence; see /entries/{id}/events" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "entry", "version", "audit_seq", "links" ], "title": "JournalEntryResponse" }, "Limits": { "properties": { "default_limit": { "type": "integer", "title": "Default Limit" }, "max_limit": { "type": "integer", "title": "Max Limit" }, "event_default_limit": { "type": "integer", "title": "Event Default Limit" }, "event_max_limit": { "type": "integer", "title": "Event Max Limit" }, "max_entry_legs": { "type": "integer", "title": "Max Entry Legs" }, "max_batch_entries": { "type": "integer", "title": "Max Batch Entries" } }, "additionalProperties": false, "type": "object", "required": [ "default_limit", "max_limit", "event_default_limit", "event_max_limit", "max_entry_legs", "max_batch_entries" ], "title": "Limits" }, "Line": { "properties": { "line_id": { "type": "string", "title": "Line Id" }, "statement_id": { "type": "string", "title": "Statement Id" }, "statement_live": { "type": "boolean", "title": "Statement Live" }, "line_no": { "type": "integer", "title": "Line No" }, "source_key": { "type": "string", "title": "Source Key" }, "dt": { "type": "string", "title": "Dt" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "commodity": { "type": "string", "title": "Commodity" }, "account_id": { "type": "string", "title": "Account Id" }, "description": { "type": "string", "title": "Description" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference" }, "raw": { "type": "string", "title": "Raw" }, "status": { "type": "string", "title": "Status", "description": "unexplained | partly_explained | booked | linked | ignored | superseded_input" }, "allocated_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Allocated Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "unexplained_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Unexplained Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "explanation": { "anyOf": [ { "$ref": "#/components/schemas/LineExplanation" }, { "type": "null" } ] }, "history": { "items": { "$ref": "#/components/schemas/LineExplanation" }, "type": "array", "title": "History" }, "entries": { "items": { "$ref": "#/components/schemas/LineEntry" }, "type": "array", "title": "Entries", "description": "the entries this line is booked or linked to, oldest first" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "line_id", "statement_id", "statement_live", "line_no", "source_key", "dt", "amount_micros", "commodity", "account_id", "description", "reference", "raw", "status", "allocated_micros", "unexplained_micros", "explanation", "history", "links" ], "title": "Line", "description": "What has become of one statement line.\n\n``status`` is derived from the live explanation, never stored, so there is exactly one answer.\n``unexplained_micros`` is the remainder, reported in every state including a fully explained line, where it\nis ``\"0\"``. ``history`` is every explanation ever written for this line, oldest first." }, "LineAllocation": { "properties": { "allocation_id": { "type": "string", "title": "Allocation Id" }, "posting_id": { "type": "string", "title": "Posting Id" }, "entry_id": { "type": "string", "title": "Entry Id" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] } }, "additionalProperties": false, "type": "object", "required": [ "allocation_id", "posting_id", "entry_id", "amount_micros" ], "title": "LineAllocation" }, "LineEntry": { "properties": { "id": { "type": "string", "title": "Id" }, "dt": { "type": "string", "title": "Dt" }, "narration": { "type": "string", "title": "Narration" }, "status": { "type": "string", "title": "Status" }, "origin": { "type": "string", "title": "Origin" }, "version": { "type": "integer", "title": "Version" }, "code": { "type": "string", "title": "Code" }, "comment": { "type": "string", "title": "Comment" }, "tags": { "items": { "items": { "type": "string" }, "type": "array" }, "type": "array", "title": "Tags" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "postings": { "items": { "$ref": "#/components/schemas/Posting" }, "type": "array", "title": "Postings" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" }, "reversed_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reversed By", "description": "the mirror entry id, when this one was reversed" } }, "additionalProperties": false, "type": "object", "required": [ "id", "dt", "narration", "status", "origin", "version", "code", "comment", "tags", "created_at", "created_by", "postings", "links" ], "title": "LineEntry", "description": "An entry a statement line is explained by, with the mirror that already reverses it, if any." }, "LineExplanation": { "properties": { "explanation_id": { "type": "string", "title": "Explanation Id" }, "line_id": { "type": "string", "title": "Line Id" }, "kind": { "type": "string", "title": "Kind", "description": "booked | linked | ignored" }, "reason": { "type": "string", "title": "Reason" }, "entry_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entry Id" }, "correction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correction Id" }, "supersedes_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supersedes Id" }, "allocations": { "items": { "$ref": "#/components/schemas/LineAllocation" }, "type": "array", "title": "Allocations" }, "allocated_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Allocated Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" } }, "additionalProperties": false, "type": "object", "required": [ "explanation_id", "line_id", "kind", "reason", "entry_id", "correction_id", "supersedes_id", "allocations", "allocated_micros", "created_at", "created_by" ], "title": "LineExplanation", "description": "One thing somebody said about a line. The chain of these is the line's history." }, "LinePage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/Line" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" }, "filtered_after_page": { "items": { "type": "string" }, "type": "array", "title": "Filtered After Page", "description": "Filters that were applied to each row's derived state *after* this page was selected. While this is non-empty a page may hold fewer items than `limit` -- even none -- with `next_cursor` still set, and that is not the end of the results: read until `next_cursor` is null. It is empty when every filter in play was applied by the query itself, and a short page then does mean the last one." } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor", "links" ], "title": "LinePage", "description": "Statement lines across every statement, by date: what each one is, and what it was booked to." }, "LineResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "line": { "$ref": "#/components/schemas/Line" }, "result": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Result", "description": "what the write did; absent when nothing was written" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "line" ], "title": "LineResponse" }, "PeriodLabel": { "properties": { "start": { "type": "string", "title": "Start" }, "end": { "type": "string", "title": "End" }, "name": { "type": "string", "title": "Name" }, "heading": { "type": "string", "title": "Heading" } }, "additionalProperties": false, "type": "object", "required": [ "start", "end", "name", "heading" ], "title": "PeriodLabel" }, "PeriodLock": { "properties": { "through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Through", "description": "the last date the books are shut through; null when nothing is closed" }, "version": { "type": "integer", "title": "Version", "description": "pass this back as expected_version on the next close or reopen" }, "close_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Close Id" } }, "additionalProperties": false, "type": "object", "required": [ "through", "version", "close_id" ], "title": "PeriodLock" }, "Posting": { "properties": { "id": { "type": "string", "title": "Id" }, "seq": { "type": "integer", "title": "Seq" }, "account_id": { "type": "string", "title": "Account Id" }, "account_path": { "type": "string", "title": "Account Path" }, "commodity": { "type": "string", "title": "Commodity" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "additionalProperties": false, "type": "object", "required": [ "id", "seq", "account_id", "account_path", "commodity", "amount_micros", "memo", "tax_code" ], "title": "Posting" }, "Provenance": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "subject": { "$ref": "#/components/schemas/ProvenanceSubject" }, "lines": { "items": { "$ref": "#/components/schemas/ProvenanceLine" }, "type": "array", "title": "Lines" }, "evidence": { "items": { "$ref": "#/components/schemas/ProvenanceEvidence" }, "type": "array", "title": "Evidence" }, "line_count": { "type": "integer", "title": "Line Count" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "subject", "lines", "evidence", "line_count", "links" ], "title": "Provenance", "description": "The answer to \"where did this come from?\": the actual document, or nothing.\n\nFor a statement line, the answer is the document it was read off. For a posting or an entry, it is the\nlines behind it, and so their documents. A subject this entity does not hold is a 404; an empty ``lines``\nlist means the subject exists but nothing links it to a document yet." }, "ProvenanceAllocation": { "properties": { "allocation_id": { "type": "string", "title": "Allocation Id" }, "explanation_id": { "type": "string", "title": "Explanation Id" }, "kind": { "type": "string", "title": "Kind" }, "posting_id": { "type": "string", "title": "Posting Id" }, "entry_id": { "type": "string", "title": "Entry Id" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] } }, "additionalProperties": false, "type": "object", "required": [ "allocation_id", "explanation_id", "kind", "posting_id", "entry_id", "amount_micros" ], "title": "ProvenanceAllocation" }, "ProvenanceEvidence": { "properties": { "evidence_id": { "type": "string", "title": "Evidence Id" }, "entry_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Entry Id" }, "statement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Id" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "locator": { "type": "string", "title": "Locator" }, "caption": { "type": "string", "title": "Caption" }, "document_id": { "type": "string", "title": "Document Id" }, "document": { "$ref": "#/components/schemas/DocumentView" } }, "additionalProperties": false, "type": "object", "required": [ "evidence_id", "entry_id", "statement_id", "page", "locator", "caption", "document_id", "document" ], "title": "ProvenanceEvidence" }, "ProvenanceLine": { "properties": { "line_id": { "type": "string", "title": "Line Id" }, "line_no": { "type": "integer", "title": "Line No" }, "source_key": { "type": "string", "title": "Source Key" }, "content_hash": { "type": "string", "title": "Content Hash" }, "dt": { "type": "string", "title": "Dt" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "description": { "type": "string", "title": "Description" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference" }, "currency": { "type": "string", "title": "Currency" }, "raw": { "type": "string", "title": "Raw" }, "statement_id": { "type": "string", "title": "Statement Id" }, "account_id": { "type": "string", "title": "Account Id" }, "commodity": { "type": "string", "title": "Commodity" }, "period_start": { "type": "string", "title": "Period Start" }, "period_end": { "type": "string", "title": "Period End" }, "statement_live": { "type": "boolean", "title": "Statement Live" }, "document_id": { "type": "string", "title": "Document Id" }, "document": { "$ref": "#/components/schemas/DocumentView" }, "allocations": { "items": { "$ref": "#/components/schemas/ProvenanceAllocation" }, "type": "array", "title": "Allocations" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "line_id", "line_no", "source_key", "content_hash", "dt", "amount_micros", "description", "reference", "currency", "raw", "statement_id", "account_id", "commodity", "period_start", "period_end", "statement_live", "document_id", "document", "allocations", "links" ], "title": "ProvenanceLine", "description": "One statement line traced back to the document it was read off." }, "ProvenanceSubject": { "properties": { "kind": { "type": "string", "title": "Kind" }, "id": { "type": "string", "title": "Id" } }, "additionalProperties": false, "type": "object", "required": [ "kind", "id" ], "title": "ProvenanceSubject" }, "ProvisionalItem": { "properties": { "expectation": { "$ref": "#/components/schemas/Expectation" }, "entry": { "$ref": "#/components/schemas/Entry" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "expectation", "entry", "links" ], "title": "ProvisionalItem", "description": "One provisional booking: the entry as it stands, and what it is waiting for." }, "ProvisionalPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/ProvisionalItem" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor" ], "title": "ProvisionalPage" }, "Readiness": { "properties": { "status": { "type": "string", "title": "Status" }, "checks": { "items": { "$ref": "#/components/schemas/Check" }, "type": "array", "title": "Checks" } }, "additionalProperties": false, "type": "object", "required": [ "status", "checks" ], "title": "Readiness" }, "Reconciliation": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "as_of": { "type": "string", "title": "As Of" }, "start": { "type": "string", "title": "Start" }, "agrees": { "type": "boolean", "title": "Agrees" }, "explained": { "type": "boolean", "title": "Explained" }, "accounts": { "items": { "$ref": "#/components/schemas/ReconciliationAccount" }, "type": "array", "title": "Accounts" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "as_of", "start", "agrees", "explained", "accounts", "links" ], "title": "Reconciliation" }, "ReconciliationAccount": { "properties": { "account_id": { "type": "string", "title": "Account Id" }, "account_path": { "type": "string", "title": "Account Path" }, "commodity": { "type": "string", "title": "Commodity" }, "as_of": { "type": "string", "title": "As Of" }, "statement_micros": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Statement Micros" }, "ledger_micros": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Ledger Micros" }, "asserted_micros": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Asserted Micros" }, "difference_micros": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Difference Micros", "description": "ledger minus statement; positive means the books hold more" }, "agrees": { "type": "boolean", "title": "Agrees" }, "statement_ids": { "items": { "type": "string" }, "type": "array", "title": "Statement Ids" }, "line_count": { "type": "integer", "title": "Line Count" }, "unexplained_lines": { "type": "integer", "title": "Unexplained Lines" }, "unexplained_micros": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unexplained Micros" }, "explained": { "type": "boolean", "title": "Explained", "description": "every loaded line through as_of has a live explanation" }, "uncovered": { "items": { "$ref": "#/components/schemas/ReconciliationGap" }, "type": "array", "title": "Uncovered", "description": "days of the period no loaded statement covers" } }, "additionalProperties": false, "type": "object", "required": [ "account_id", "account_path", "commodity", "as_of", "statement_micros", "ledger_micros", "asserted_micros", "difference_micros", "agrees", "statement_ids", "line_count", "unexplained_lines", "unexplained_micros", "explained", "uncovered" ], "title": "ReconciliationAccount", "description": "One cash account and commodity at one date, from both sides.\n\n``statement_micros`` is the loaded statements' own arithmetic: the earliest declared opening plus every line\nup to ``as_of``. ``asserted_micros`` is a closing balance the bank actually printed for that exact date,\nwhen there is one, reported beside the derived figure rather than instead of it. ``null`` anywhere means\n\"not knowable here\", never zero.\n\n``agrees`` and ``explained`` answer different questions. A statement can balance to the penny with every\nline unclassified, so the count of unexplained lines is reported beside the difference, not folded into it." }, "ReconciliationGap": { "properties": { "start": { "type": "string", "title": "Start" }, "end": { "type": "string", "title": "End" } }, "additionalProperties": false, "type": "object", "required": [ "start", "end" ], "title": "ReconciliationGap" }, "Register": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "account_id": { "type": "string", "title": "Account Id" }, "account_path": { "type": "string", "title": "Account Path" }, "start": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Start" }, "end": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "End" }, "opening_micros": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Opening Micros" }, "items": { "items": { "$ref": "#/components/schemas/RegisterLine" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "account_id", "account_path", "start", "end", "opening_micros", "items", "next_cursor", "links" ], "title": "Register" }, "RegisterLine": { "properties": { "entry_id": { "type": "string", "title": "Entry Id" }, "dt": { "type": "string", "title": "Dt" }, "seq": { "type": "integer", "title": "Seq" }, "narration": { "type": "string", "title": "Narration" }, "origin": { "type": "string", "title": "Origin" }, "account_id": { "type": "string", "title": "Account Id" }, "account_path": { "type": "string", "title": "Account Path" }, "commodity": { "type": "string", "title": "Commodity" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "running_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Running Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "memo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memo" }, "tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Code" } }, "additionalProperties": false, "type": "object", "required": [ "entry_id", "dt", "seq", "narration", "origin", "account_id", "account_path", "commodity", "amount_micros", "running_micros", "memo", "tax_code" ], "title": "RegisterLine" }, "ReopenPeriodResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "close_id": { "type": "string", "title": "Close Id" }, "kind": { "type": "string", "title": "Kind" }, "reopened_close_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reopened Close Id" }, "lock": { "$ref": "#/components/schemas/PeriodLock" }, "snapshot": { "$ref": "#/components/schemas/CloseSnapshot" }, "audit_seq": { "type": "integer", "title": "Audit Seq" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "close_id", "kind", "reopened_close_id", "lock", "snapshot", "audit_seq", "links" ], "title": "ReopenPeriodResponse" }, "ReportLine": { "properties": { "account_id": { "type": "string", "title": "Account Id" }, "account_path": { "type": "string", "title": "Account Path" }, "type": { "type": "string", "title": "Type" }, "commodity": { "type": "string", "title": "Commodity" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] } }, "additionalProperties": false, "type": "object", "required": [ "account_id", "account_path", "type", "commodity", "amount_micros" ], "title": "ReportLine" }, "ShapedGroup": { "properties": { "key": { "type": "string", "title": "Key" }, "heading": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Heading", "description": "null when the group holds a single account and needs no heading" }, "subtotal_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Subtotal Micros" }, "comparative_subtotal_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Subtotal Micros" }, "lines": { "items": { "$ref": "#/components/schemas/ShapedLine" }, "type": "array", "title": "Lines" } }, "additionalProperties": false, "type": "object", "required": [ "key", "heading", "lines" ], "title": "ShapedGroup" }, "ShapedLine": { "properties": { "key": { "type": "string", "title": "Key" }, "account_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Account Id", "description": "the account a line links to; null for a synthetic row" }, "label": { "type": "string", "title": "Label" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "comparative_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Micros" } }, "additionalProperties": false, "type": "object", "required": [ "key", "account_id", "label", "amount_micros" ], "title": "ShapedLine" }, "ShapedSection": { "properties": { "key": { "type": "string", "title": "Key" }, "title": { "type": "string", "title": "Title" }, "total_label": { "type": "string", "title": "Total Label" }, "total_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Total Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "comparative_total_micros": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$" }, { "type": "null" } ], "title": "Comparative Total Micros" }, "groups": { "items": { "$ref": "#/components/schemas/ShapedGroup" }, "type": "array", "title": "Groups" } }, "additionalProperties": false, "type": "object", "required": [ "key", "title", "total_label", "total_micros", "groups" ], "title": "ShapedSection" }, "Snapshot": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "id": { "type": "string", "title": "Id" }, "snapshot_seq_of_snapshot": { "type": "integer", "title": "Snapshot Seq Of Snapshot" }, "state_hash": { "type": "string", "title": "State Hash" }, "through": { "type": "string", "title": "Through" }, "manifest": { "title": "Manifest" }, "report": { "title": "Report" }, "checks": { "title": "Checks" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "id", "snapshot_seq_of_snapshot", "state_hash", "through", "manifest", "report", "checks", "created_at", "created_by", "links" ], "title": "Snapshot" }, "Statement": { "properties": { "statement_id": { "type": "string", "title": "Statement Id" }, "account_id": { "type": "string", "title": "Account Id" }, "account_path": { "type": "string", "title": "Account Path" }, "commodity": { "type": "string", "title": "Commodity" }, "period_start": { "type": "string", "title": "Period Start" }, "period_end": { "type": "string", "title": "Period End" }, "opening_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Opening Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "closing_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Closing Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "opening_verified": { "type": "boolean", "title": "Opening Verified", "description": "true only when the opening equals a recorded prior closing" }, "opening_basis": { "type": "string", "title": "Opening Basis", "description": "which of the three opening cases this is" }, "prior_statement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Prior Statement Id" }, "line_count": { "type": "integer", "title": "Line Count" }, "lines_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Lines Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "document_id": { "type": "string", "title": "Document Id" }, "document": { "$ref": "#/components/schemas/DocumentView" }, "page": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Page" }, "locator": { "type": "string", "title": "Locator" }, "reason": { "type": "string", "title": "Reason" }, "replaces_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replaces Id", "description": "the statement this one replaces, when it is a replacement" }, "replaced_by_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Replaced By Id", "description": "the statement that replaced this one, when one has" }, "live": { "type": "boolean", "title": "Live", "description": "nothing replaces this statement" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "statement_id", "account_id", "account_path", "commodity", "period_start", "period_end", "opening_micros", "closing_micros", "opening_verified", "opening_basis", "prior_statement_id", "line_count", "lines_micros", "document_id", "document", "page", "locator", "reason", "replaces_id", "replaced_by_id", "live", "created_at", "created_by", "links" ], "title": "Statement" }, "StatementLine": { "properties": { "line_id": { "type": "string", "title": "Line Id" }, "statement_id": { "type": "string", "title": "Statement Id" }, "line_no": { "type": "integer", "title": "Line No" }, "source_key": { "type": "string", "title": "Source Key" }, "content_hash": { "type": "string", "title": "Content Hash" }, "dt": { "type": "string", "title": "Dt" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "description": { "type": "string", "title": "Description" }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reference" }, "currency": { "type": "string", "title": "Currency" }, "raw": { "type": "string", "title": "Raw" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "line_id", "statement_id", "line_no", "source_key", "content_hash", "dt", "amount_micros", "description", "reference", "currency", "raw", "links" ], "title": "StatementLine" }, "StatementLinePage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "statement_id": { "type": "string", "title": "Statement Id" }, "items": { "items": { "$ref": "#/components/schemas/StatementLine" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "statement_id", "items", "next_cursor", "links" ], "title": "StatementLinePage" }, "StatementPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/Statement" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor" ], "title": "StatementPage" }, "StatementResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "statement": { "$ref": "#/components/schemas/Statement" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "statement" ], "title": "StatementResponse" }, "StatementWriteResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "statement": { "$ref": "#/components/schemas/Statement" }, "audit_seq": { "type": "integer", "title": "Audit Seq", "description": "the statement.loaded / statement.replaced action's event sequence" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "statement", "audit_seq" ], "title": "StatementWriteResponse", "description": "The reply to loading or replacing a statement: the statement, and the action that recorded it.\n\nThe read routes use ``StatementResponse``, which has no ``audit_seq`` because a read has no action behind\nit. Hence a separate model rather than an optional field." }, "StatementsDocument": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "report": { "type": "string", "title": "Report" }, "commodity": { "type": "string", "title": "Commodity", "description": "the commodity the document leads with: the one requested, or the base one" }, "period": { "$ref": "#/components/schemas/PeriodLabel" }, "comparative": { "anyOf": [ { "$ref": "#/components/schemas/ComparativeLabel" }, { "type": "null" } ] }, "as_of": { "type": "string", "title": "As Of" }, "footnote": { "type": "string", "title": "Footnote", "description": "the sign convention and the commodities this document does not show" }, "statements": { "items": { "$ref": "#/components/schemas/CommodityStatements" }, "type": "array", "title": "Statements", "description": "one shaped income statement and balance sheet per commodity these books hold in the period" }, "other_commodities": { "items": { "type": "string" }, "type": "array", "title": "Other Commodities" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "report", "commodity", "period", "comparative", "as_of", "footnote", "statements", "other_commodities", "links" ], "title": "StatementsDocument" }, "TrialBalance": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "report": { "type": "string", "title": "Report" }, "through": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Through" }, "lines": { "items": { "$ref": "#/components/schemas/ReportLine" }, "type": "array", "title": "Lines" }, "totals": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Totals" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "report", "through", "lines", "totals", "links" ], "title": "TrialBalance" }, "UnrecoveredItem": { "properties": { "record": { "$ref": "#/components/schemas/UnrecoveredRecord" }, "entry": { "$ref": "#/components/schemas/Entry" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "record", "entry", "links" ], "title": "UnrecoveredItem" }, "UnrecoveredPage": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "items": { "items": { "$ref": "#/components/schemas/UnrecoveredItem" }, "type": "array", "title": "Items" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" }, "state": { "type": "string", "title": "State" }, "totals": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Totals", "description": "per commodity, never summed across them" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "items", "next_cursor", "state", "totals" ], "title": "UnrecoveredPage" }, "UnrecoveredRecord": { "properties": { "id": { "type": "string", "title": "Id" }, "entry_id": { "type": "string", "title": "Entry Id" }, "posting_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Posting Id" }, "commodity": { "type": "string", "title": "Commodity" }, "amount_micros": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "title": "Amount Micros", "description": "Signed integer micro-units (millionths) as a base-10 string; never a JSON number.", "examples": [ "-12000000" ] }, "state": { "type": "string", "title": "State", "description": "unrecovered | recovered | forgone" }, "tax_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Tax Code" }, "reason": { "type": "string", "title": "Reason" }, "recoverable_until": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recoverable Until" }, "recovered_entry_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Recovered Entry Id" }, "supersedes_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supersedes Id" }, "created_at": { "type": "string", "title": "Created At" }, "created_by": { "type": "string", "title": "Created By" } }, "additionalProperties": false, "type": "object", "required": [ "id", "entry_id", "posting_id", "commodity", "amount_micros", "state", "tax_code", "reason", "recoverable_until", "recovered_entry_id", "supersedes_id", "created_at", "created_by" ], "title": "UnrecoveredRecord" }, "UnrecoveredResponse": { "properties": { "entity_id": { "type": "string", "title": "Entity Id" }, "legal_name": { "type": "string", "title": "Legal Name" }, "base_currency": { "type": "string", "title": "Base Currency" }, "snapshot_seq": { "type": "integer", "title": "Snapshot Seq" }, "record": { "$ref": "#/components/schemas/UnrecoveredRecord" }, "history": { "items": { "$ref": "#/components/schemas/UnrecoveredRecord" }, "type": "array", "title": "History", "description": "every record about this entry, oldest first" }, "links": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Links" } }, "additionalProperties": false, "type": "object", "required": [ "entity_id", "legal_name", "base_currency", "snapshot_seq", "record", "history", "links" ], "title": "UnrecoveredResponse" } } } }