# Ghaem Gold API

> Live OpenAPI documentation for 19 APIs and 107 operations. Generated from the specs on every request, so it is never stale. Revision 51ce12b9664f.

## APIs

- [Assets API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/assets.json): The asset registry: what a balance line can be denominated in — Rial, gold and silver weights, individual coin variants, bullion, and foreign currencies — plus…
- [Audit Log API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/audit.json): «مشاهده لاگ‌ها» — the append-only, tamper-evident record of everything that happened in the system, and the tool that proves it has not been altered. Every mut…
- [Admin Audit Log API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/audit-admin.json): Exporting the audit trail — a single endpoint, and the most tightly gated read in the whole API. Browsing the trail, reading one row, listing the action catalo…
- [Authentication API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/auth.json): Operator sign-in, refresh-token rotation and session management for the Ghaem Gold panel. §4.1 — the only population that signs in is the operator (panel staff…
- [Bank Accounts API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/bank-accounts.json): Counterparty bank accounts — the destinations settlement money is actually sent to — plus the read-only bank catalog they are classified against. An account is…
- [Admin Bank Accounts API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/bank-accounts-admin.json): The three flags on a bank account that govern how the settlement matching engine treats it: whether the account is excluded from matching altogether, and wheth…
- [Files API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/files.json): Retrieval of stored receipt images. Two routes, with deliberately different security models. Files in this system live in private object storage. Nothing is ev…
- [Financial Records API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/financial-records.json): «سوابق مالی» — multi-asset counterparty balances mirrored from the accounting system: the current book, one record's full snapshot history with per-asset delta…
- [Health and Metrics API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/health.json): Operational endpoints: two orchestrator probes and one Prometheus scrape target. None of them requires authentication, and none of them is part of the panel's …
- [Ingestion API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/ingestion.json): «همگام‌سازی» — the pipeline that pulls parties and balances from the external accounting system, and the operator surface for watching it. Three ideas run thro…
- [Admin Ingestion API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/ingestion-admin.json): The three ingestion operations that change canonical data by re-deriving it from stored vendor payloads: resolving a quarantine row, reprocessing a single raw …
- [Matching API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/matching.json): «لیست تطبیق» — the settlement allocation engine. It decides which debtor pays which creditor, into which nominated bank account, for how much. This is not a re…
- [Admin Matching API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/matching-admin.json): The three decisions in the settlement matching engine that have money attached: freezing a plan, issuing payment orders from it, and changing the engine's para…
- [Admin Operators API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/operators-admin.json): Management of operators — the panel staff who sign in and hold permissions. §4.1 — this is not the counterparty list: a party is an external entity mirrored fr…
- [Parties API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/parties.json): The counterparty list — «لیست کاربران» in the panel sidebar. A party is an external entity mirrored from the accounting system: it never signs in, holds no per…
- [Admin Parties API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/parties-admin.json): Administrator-only control over whether a counterparty takes part in settlement matching at all. Everything else about a party — searching, reading, editing lo…
- [Party Groups API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/party-groups.json): Counterparty groups — صندوق / ويترين داران / خانگي and anything the sync has met since. A party group classifies an external counterparty; it confers no access…
- [Payments API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/payments.json): «سوابق پرداخت» — payment orders, the state machine they move through, and the receipt (فیش) evidence attached to them. Payments here are recorded, not executed…
- [Admin Roles and Permissions API](http://docs.aghajani-gold.mrtakrobot.ir/openapi/rbac-admin.json): The panel's access-control settings: the panel roles operators are assigned to, and the read-only permission catalog those roles are built from. §4.1 — these a…

## Machine endpoints

- [Operation index](http://docs.aghajani-gold.mrtakrobot.ir/index.json): every operation across every API, one compact JSON document.
- [Revision](http://docs.aghajani-gold.mrtakrobot.ir/revision.json): content hashes; poll this to tell whether anything changed.
- [Full documentation](http://docs.aghajani-gold.mrtakrobot.ir/llms-full.txt): every operation and every convention as plain text.
- MCP endpoint: POST http://docs.aghajani-gold.mrtakrobot.ir/mcp (tools: list_apis, search_operations, get_operation, get_schema, get_conventions, get_spec).

## Operations

- `GET /api/v1/assets` — List assets, pending-review ones first. (id `listAssets`, app `assets` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/assets/{id}` — Retrieve one asset. (id `getAsset`, app `assets` [bearer], responses 200,401,403,404,429,500)
- `PATCH /api/v1/assets/{id}` — Name or reclassify an asset. (id `updateAsset`, app `assets` [bearer], responses 200,400,401,403,404,409,429,500)
- `GET /api/v1/audit-logs` — List audit log entries, newest first. (id `listAuditLogs`, app `audit` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/audit-logs/actions` — List the catalog of recordable actions. (id `listAuditActions`, app `audit` [bearer], responses 200,401,403,429,500)
- `GET /api/v1/audit-logs/verify-chain` — Verify the audit log's hash chain. (id `verifyAuditChain`, app `audit` [bearer], responses 200,401,403,429,500)
- `GET /api/v1/audit-logs/{id}` — Retrieve one audit log entry. (id `getAuditLog`, app `audit` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/audit-logs/export` — Export matching audit log entries. (id `adminExportAuditLogs`, app `audit-admin` [bearer], responses 200,400,401,403,429,500)
- `POST /api/v1/auth/login` — Sign in and obtain an access/refresh token pair. (id `login`, app `auth`, responses 200,400,401,429,500)
- `POST /api/v1/auth/refresh` — Rotate a refresh token for a new token pair. (id `refreshSession`, app `auth`, responses 200,400,401,423,429,500)
- `POST /api/v1/auth/logout` — End the current session, or every session this operator holds. (id `logout`, app `auth` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/auth/me` — Read the signed-in operator and their effective permissions. (id `getCurrentOperator`, app `auth` [bearer], responses 200,401,403,429,500)
- `POST /api/v1/auth/change-password` — Change your own password. (id `changePassword`, app `auth` [bearer], responses 200,400,401,403,429,500)
- `POST /api/v1/auth/reauth` — Re-enter your password to unlock dangerous actions for five minutes. (id `reauthenticate`, app `auth` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/banks` — List the bank catalog. (id `listBanks`, app `bank-accounts` [bearer], responses 200,401,403,429,500)
- `GET /api/v1/parties/{partyId}/bank-accounts` — List a party's bank accounts. (id `listPartyBankAccounts`, app `bank-accounts` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/parties/{partyId}/bank-accounts` — Add a bank account to a party. (id `createPartyBankAccount`, app `bank-accounts` [bearer], responses 201,400,401,403,404,409,429,500)
- `GET /api/v1/bank-accounts/{id}` — Retrieve one bank account. (id `getBankAccount`, app `bank-accounts` [bearer], responses 200,401,403,404,429,500)
- `DELETE /api/v1/bank-accounts/{id}` — Soft-delete a bank account. (id `deleteBankAccount`, app `bank-accounts` [bearer], responses 200,401,403,404,409,429,500)
- `PATCH /api/v1/bank-accounts/{id}` — Edit a bank account's identifiers or details. (id `updateBankAccount`, app `bank-accounts` [bearer], responses 200,400,401,403,404,409,429,500)
- `POST /api/v1/bank-accounts/{id}/restore` — Restore a soft-deleted bank account. (id `restoreBankAccount`, app `bank-accounts` [bearer], responses 200,400,401,403,404,409,429,500)
- `POST /api/v1/bank-accounts/{id}/set-default` — Nominate an account as the party's default destination. (id `setDefaultBankAccount`, app `bank-accounts` [bearer], responses 200,400,401,403,404,429,500)
- `GET /api/v1/bank-accounts/{id}/reveal-iban` — Reveal an account's full IBAN. (id `revealBankAccountIban`, app `bank-accounts` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/bank-accounts/{id}/matching-exclusion` — Exclude a bank account from settlement matching. (id `adminExcludeBankAccountFromMatching`, app `bank-accounts-admin` [bearer], responses 200,400,401,403,404,429,500)
- `DELETE /api/v1/bank-accounts/{id}/matching-exclusion` — Return a bank account to settlement matching. (id `adminRemoveBankAccountMatchingExclusion`, app `bank-accounts-admin` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/bank-accounts/{id}/company-flag` — Mark or unmark a bank account as a company account. (id `adminSetBankAccountCompanyFlag`, app `bank-accounts-admin` [bearer], responses 200,400,401,403,404,429,500)
- `GET /api/v1/files/{id}/thumb` — Get a short-lived signed URL for a receipt's thumbnail. (id `getFileThumbnailUrl`, app `files` [bearer], responses 200,401,403,404,409,429,500)
- `GET /api/v1/files/local-object` — Serve a stored object against a signed URL. (id `getLocalObject`, app `files`, responses 200,403,429,500)
- `GET /api/v1/financial-records` — List the current book of counterparty balances. (id `listFinancialRecords`, app `financial-records` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/financial-records/orphans` — Report balances that have no party record. (id `getOrphanReport`, app `financial-records` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/financial-records/{externalCode}` — Retrieve one financial record by its accounting code. (id `getFinancialRecord`, app `financial-records` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/financial-records/{externalCode}/history` — List one code's snapshot history with per-asset deltas. (id `listFinancialRecordHistory`, app `financial-records` [bearer], responses 200,400,401,403,404,429,500)
- `GET /api/v1/health/live` — Report that the process is alive. (id `getLiveness`, app `health`, responses 200,500)
- `GET /api/v1/health/ready` — Report whether every dependency is reachable. (id `getReadiness`, app `health`, responses 200,500,503)
- `GET /metrics` — Expose Prometheus metrics. (id `getMetrics`, app `health`, responses 200,500)
- `GET /api/v1/sync/runs` — List synchronisation runs. (id `listSyncRuns`, app `ingestion` [bearer], responses 200,400,401,403,429,500)
- `POST /api/v1/sync/runs` — Trigger a synchronisation run for one entity. (id `triggerSyncRun`, app `ingestion` [bearer], responses 202,400,401,403,429,500,503)
- `GET /api/v1/sync/raw-records` — List raw external records. (id `listRawRecords`, app `ingestion` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/sync/raw-records/{id}` — Retrieve one raw external record. (id `getRawRecord`, app `ingestion` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/sync/quarantine` — List quarantined records. (id `listQuarantine`, app `ingestion` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/sync/quarantine/{id}` — Retrieve one quarantined record. (id `getQuarantineEntry`, app `ingestion` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/sync/replay/{jobId}` — Poll a bulk replay job's progress. (id `getReplayStatus`, app `ingestion` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/sync/quarantine/{id}/resolve` — Resolve a quarantined record. (id `adminResolveQuarantine`, app `ingestion-admin` [bearer], responses 200,400,401,403,404,429,500)
- `POST /api/v1/sync/raw-records/{id}/reprocess` — Reprocess one raw record through the current transformer. (id `adminReprocessRawRecord`, app `ingestion-admin` [bearer], responses 200,400,401,403,404,429,500)
- `POST /api/v1/sync/replay` — Bulk-replay stored raw records through the current transformer. (id `adminStartReplay`, app `ingestion-admin` [bearer], responses 202,400,401,403,409,429,500)
- `GET /api/v1/matching/board` — Retrieve the live matching board. (id `getMatchingBoard`, app `matching` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/matching/board/stats` — Retrieve the board's KPI header. (id `getMatchingBoardStats`, app `matching` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/matching/pool` — List unallocated debtors and creditors with no box. (id `getMatchingPool`, app `matching` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/matching/export` — Export the matching board as CSV or XLSX. (id `exportMatchingBoard`, app `matching` [bearer], responses 200,400,401,403,404,429,500)
- `POST /api/v1/matching/recompute` — Queue a global rebuild of the matching board. (id `recomputeMatchingBoard`, app `matching` [bearer], responses 202,401,403,409,429,500)
- `GET /api/v1/matching/runs` — List matching runs. (id `listMatchingRuns`, app `matching` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/matching/runs/{id}` — Retrieve one matching run. (id `getMatchingRun`, app `matching` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/matching/groups/{id}` — Retrieve one matching box in full. (id `getMatchingGroup`, app `matching` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/matching/groups/{id}/candidates` — List debtors that could be allocated to this box. (id `listMatchingCandidates`, app `matching` [bearer], responses 200,400,401,403,404,429,500)
- `POST /api/v1/matching/groups/{id}/recompute` — Rebuild one matching box synchronously. (id `recomputeMatchingGroup`, app `matching` [bearer], responses 200,401,403,404,409,429,500)
- `POST /api/v1/matching/allocations` — Allocate a debtor to a target by hand. (id `createMatchingAllocation`, app `matching` [bearer], responses 201,400,401,403,404,409,422,429,500)
- `DELETE /api/v1/matching/allocations/{id}` — Remove an allocation. (id `deleteMatchingAllocation`, app `matching` [bearer], responses 200,400,401,403,404,409,429,500)
- `PATCH /api/v1/matching/allocations/{id}` — Change an allocation's amount. (id `updateMatchingAllocation`, app `matching` [bearer], responses 200,400,401,403,404,409,422,429,500)
- `POST /api/v1/matching/allocations/{id}/move` — Move a debtor from one box to another. (id `moveMatchingAllocation`, app `matching` [bearer], responses 200,400,401,403,404,409,422,429,500)
- `GET /api/v1/matching/settings` — Read the live matching settings. (id `getMatchingSettings`, app `matching` [bearer], responses 200,401,403,429,500)
- `POST /api/v1/matching/groups/{id}/lock` — Freeze a matching box. (id `adminLockMatchingGroup`, app `matching-admin` [bearer], responses 200,400,401,403,404,409,429,500)
- `POST /api/v1/matching/groups/{id}/unlock` — Release a frozen matching box. (id `adminUnlockMatchingGroup`, app `matching-admin` [bearer], responses 200,400,401,403,404,409,429,500)
- `POST /api/v1/matching/groups/{id}/issue-payments` — Issue payment orders from a frozen matching box. (id `adminIssueMatchingPayments`, app `matching-admin` [bearer], responses 200,400,401,403,404,409,429,500)
- `PATCH /api/v1/matching/settings` — Change the matching engine's parameters. (id `adminUpdateMatchingSettings`, app `matching-admin` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/operators` — List panel operators. (id `adminListOperators`, app `operators-admin` [bearer], responses 200,400,401,403,429,500)
- `POST /api/v1/operators` — Create a panel operator. (id `adminCreateOperator`, app `operators-admin` [bearer], responses 201,400,401,403,404,409,429,500)
- `GET /api/v1/operators/{id}` — Retrieve one panel operator. (id `adminGetOperator`, app `operators-admin` [bearer], responses 200,401,403,404,429,500)
- `DELETE /api/v1/operators/{id}` — Soft-delete an operator. (id `adminDeleteOperator`, app `operators-admin` [bearer], responses 200,401,403,404,409,429,500)
- `PATCH /api/v1/operators/{id}` — Update an operator's display name, email or role. (id `adminUpdateOperator`, app `operators-admin` [bearer], responses 200,400,401,403,404,409,429,500)
- `POST /api/v1/operators/{id}/suspend` — Suspend an operator and end their sessions immediately. (id `adminSuspendOperator`, app `operators-admin` [bearer], responses 200,401,403,404,409,429,500)
- `POST /api/v1/operators/{id}/activate` — Reactivate a suspended operator and clear their lockout. (id `adminActivateOperator`, app `operators-admin` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/operators/{id}/reset-password` — Reset an operator's password and end their sessions. (id `adminResetOperatorPassword`, app `operators-admin` [bearer], responses 200,400,401,403,404,429,500)
- `GET /api/v1/parties` — List and search parties. (id `listParties`, app `parties` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/parties/{id}` — Retrieve one party with its financial and contact context. (id `getParty`, app `parties` [bearer], responses 200,401,403,404,429,500)
- `PATCH /api/v1/parties/{id}` — Edit a party's locally owned fields. (id `updateParty`, app `parties` [bearer], responses 200,400,401,403,404,409,429,500)
- `GET /api/v1/parties/{id}/phones` — List a party's contact numbers. (id `listPartyPhones`, app `parties` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/parties/{id}/phones` — Add a contact number to a party. (id `createPartyPhone`, app `parties` [bearer], responses 201,400,401,403,404,409,429,500)
- `DELETE /api/v1/parties/{id}/phones/{phoneId}` — Remove a contact number. (id `deletePartyPhone`, app `parties` [bearer], responses 200,401,403,404,429,500)
- `PATCH /api/v1/parties/{id}/phones/{phoneId}` — Edit a contact number. (id `updatePartyPhone`, app `parties` [bearer], responses 200,400,401,403,404,409,429,500)
- `POST /api/v1/parties/{id}/phones/{phoneId}/set-primary` — Nominate a contact number as the party's primary. (id `setPrimaryPartyPhone`, app `parties` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/parties/{id}/matching-exclusion` — Exclude a party from settlement matching. (id `adminExcludePartyFromMatching`, app `parties-admin` [bearer], responses 200,400,401,403,404,429,500)
- `DELETE /api/v1/parties/{id}/matching-exclusion` — Return a party to settlement matching. (id `adminRemovePartyMatchingExclusion`, app `parties-admin` [bearer], responses 200,401,403,404,429,500)
- `GET /api/v1/party-groups` — List party groups, unconfirmed ones first. (id `listPartyGroups`, app `party-groups` [bearer], responses 200,400,401,403,429,500)
- `POST /api/v1/party-groups` — Register a party group manually. (id `createPartyGroup`, app `party-groups` [bearer], responses 201,400,401,403,409,429,500)
- `GET /api/v1/party-groups/{id}` — Retrieve one party group. (id `getPartyGroup`, app `party-groups` [bearer], responses 200,401,403,404,429,500)
- `DELETE /api/v1/party-groups/{id}` — Delete an empty party group. (id `deletePartyGroup`, app `party-groups` [bearer], responses 200,401,403,404,409,429,500)
- `PATCH /api/v1/party-groups/{id}` — Name and confirm a party group. (id `updatePartyGroup`, app `party-groups` [bearer], responses 200,400,401,403,404,409,429,500)
- `GET /api/v1/payments` — List payment orders with filters. (id `listPayments`, app `payments` [bearer], responses 200,400,401,403,429,500)
- `POST /api/v1/payments` — Create a payment order. (id `createPayment`, app `payments` [bearer], responses 201,400,401,403,404,409,429,500)
- `GET /api/v1/payments/summary` — Aggregate payment counts and sums for the dashboard. (id `getPaymentsSummary`, app `payments` [bearer], responses 200,401,403,429,500)
- `GET /api/v1/payments/hygiene` — Run the receipt hygiene sweep and report its findings. (id `getPaymentHygieneReport`, app `payments` [bearer], responses 200,401,403,429,500)
- `GET /api/v1/payments/export` — Export the matching payment orders as CSV or XLSX. (id `exportPayments`, app `payments` [bearer], responses 200,400,401,403,429,500)
- `GET /api/v1/payments/{id}` — Retrieve one payment order. (id `getPayment`, app `payments` [bearer], responses 200,401,403,404,429,500)
- `DELETE /api/v1/payments/{id}` — Soft-delete a payment order. (id `deletePayment`, app `payments` [bearer], responses 200,401,403,404,409,429,500)
- `PATCH /api/v1/payments/{id}` — Edit a draft or issued payment order. (id `updatePayment`, app `payments` [bearer], responses 200,400,401,403,404,409,429,500)
- `GET /api/v1/payments/{id}/transitions` — List a payment's status history. (id `listPaymentTransitions`, app `payments` [bearer], responses 200,401,403,404,429,500)
- `POST /api/v1/payments/{id}/transitions` — Move a payment to another status. (id `transitionPayment`, app `payments` [bearer], responses 200,400,401,403,404,409,429,500)
- `GET /api/v1/payments/{id}/receipt` — Get a short-lived signed URL for a payment's receipt. (id `getPaymentReceiptUrl`, app `payments` [bearer], responses 200,401,403,404,409,429,500)
- `POST /api/v1/payments/{id}/receipt` — Upload or replace a payment's receipt. (id `uploadPaymentReceipt`, app `payments` [bearer], responses 200,400,401,403,404,409,413,415,429,500)
- `DELETE /api/v1/payments/{id}/receipt` — Detach a payment's receipt. (id `deletePaymentReceipt`, app `payments` [bearer], responses 200,401,403,404,409,429,500)
- `GET /api/v1/panel-roles` — List panel roles with their grants and operator counts. (id `adminListPanelRoles`, app `rbac-admin` [bearer], responses 200,401,403,429,500)
- `POST /api/v1/panel-roles` — Create an empty panel role. (id `adminCreatePanelRole`, app `rbac-admin` [bearer], responses 201,400,401,403,409,429,500)
- `GET /api/v1/panel-roles/{id}` — Retrieve one panel role. (id `adminGetPanelRole`, app `rbac-admin` [bearer], responses 200,401,403,404,429,500)
- `DELETE /api/v1/panel-roles/{id}` — Delete a panel role. (id `adminDeletePanelRole`, app `rbac-admin` [bearer], responses 200,401,403,404,409,429,500)
- `PATCH /api/v1/panel-roles/{id}` — Rename or re-describe a panel role. (id `adminUpdatePanelRole`, app `rbac-admin` [bearer], responses 200,400,401,403,404,409,429,500)
- `PUT /api/v1/panel-roles/{id}/permissions` — Replace a role's entire permission set. (id `adminSetPanelRolePermissions`, app `rbac-admin` [bearer], responses 200,400,401,403,404,409,429,500)
- `GET /api/v1/permissions` — List the permission catalog, grouped. (id `adminListPermissions`, app `rbac-admin` [bearer], responses 200,401,403,429,500)