{ "openapi": "3.1.0", "info": { "title": "BillMate API", "version": "1.0.0", "description": "BillMate’s free API for alternative clients. Authenticated with a personal key generated from your profile. Amounts are always in minor units (cents)." }, "servers": [ { "url": "https://billmate.it" } ], "security": [ { "apiKey": [] } ], "paths": { "/api/me": { "get": { "operationId": "me", "tags": [ "Account and reference data" ], "summary": "Profile of the key’s user", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "email": "anna@example.com", "avatarUrl": null, "locale": "it", "defaultCurrency": "EUR", "onboarded": true, "createdAt": "2026-10-21T15:11:20.346Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/meta": { "get": { "operationId": "meta", "tags": [ "Account and reference data" ], "summary": "Enabled currencies, categories and limits", "description": "Reference data for creating expenses: currencies (with decimals), platform and group categories, and the suggested rate between two currencies.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "description": "Also includes this group’s custom categories.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Source currency for the suggested rate.", "schema": { "type": "string", "minLength": 3, "maxLength": 3 } }, { "name": "to", "in": "query", "required": false, "description": "Target currency for the suggested rate.", "schema": { "type": "string", "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "currencies": [ { "code": "EUR", "name": "Euro", "symbol": "€", "decimals": 2, "enabled": true } ], "categories": [ { "id": "c1…", "key": "food", "name": null, "labels": { "it": "Cibo", "en": "Food" }, "icon": "utensils", "color": "#c2410c" } ], "rate": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/dashboard": { "get": { "operationId": "dashboard", "tags": [ "Account and reference data" ], "summary": "Overview: totals, groups, friends and recent activity", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "totals": [ { "currency": "EUR", "owedToYou": 1500, "youOwe": 0, "net": 1500 } ], "groups": [ "…" ], "friends": [ "…" ], "friendCount": 1, "incomingRequests": 0, "activity": [ "…" ], "unread": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/balances": { "get": { "operationId": "balances", "tags": [ "Account and reference data" ], "summary": "Balances: total, per friend and per group", "description": "Amounts in minor units. A positive value means you are owed money, a negative one that you owe.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "totals": [ { "currency": "EUR", "owedToYou": 1500, "youOwe": 0, "net": 1500 } ], "friends": { "b93e456c-f17f-4d42-a36f-96f75dad14f3": [ { "currency": "EUR", "amountMinor": 1500 } ] }, "groups": { "d19d0200-ea0e-4d0a-a899-2b96bf06ac03": { "currency": "EUR", "net": 1500 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/activity": { "get": { "operationId": "activity", "tags": [ "Account and reference data" ], "summary": "Activity feed", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "before", "in": "query", "required": false, "description": "ISO 8601 date: returns only earlier activity (pagination, 50 at a time).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "items": [ { "id": "a1…", "type": "expense_added", "entityType": "expense", "entityId": "1a7fed19-c0b0-4607-aef2-8422b592dc14", "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "data": { "description": "Cena in Trastevere", "amountMinor": 4000, "currency": "EUR" }, "createdAt": "2026-10-21T15:11:20.735Z", "actor": { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "avatarUrl": null } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/groups": { "get": { "operationId": "groups_list", "tags": [ "Groups" ], "summary": "List your groups", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "`true` for archived groups (default: `false`).", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "items": [ { "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "name": "Weekend a Roma", "type": "trip", "currency": "EUR", "archivedAt": null, "role": "owner", "memberCount": 2, "members": [ { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "avatarUrl": null }, { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "avatarUrl": null } ], "myBalanceMinor": 1500 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "post": { "operationId": "groups_create", "tags": [ "Groups" ], "summary": "Create a group", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Group name (max 60 characters)." }, "type": { "default": "other", "type": "string", "enum": [ "trip", "home", "couple", "event", "family", "other" ], "description": "Group type." }, "currency": { "default": "EUR", "type": "string", "pattern": "^[A-Z]{3}$", "description": "Group currency (ISO 4217, default EUR)." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Optional notes." }, "simplifyDebts": { "default": true, "type": "boolean", "description": "Simplify debts into fewer payments (default: true)." }, "memberIds": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Friends to add right away (they must already be your friends)." } }, "required": [ "name" ] }, "example": { "name": "Weekend a Roma", "type": "trip", "currency": "EUR", "simplifyDebts": true } } } } } }, "/api/groups/{id}": { "get": { "operationId": "groups_get", "tags": [ "Groups" ], "summary": "Group detail, with members and balances", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "group": { "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "name": "Weekend a Roma", "type": "trip", "currency": "EUR", "simplifyDebts": true, "archivedAt": null }, "myRole": "owner", "members": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "role": "owner" } ], "balances": { "currency": "EUR", "simplified": true, "net": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "amountMinor": 1500 }, { "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "amountMinor": -1500 } ], "transfers": [ { "from": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "to": "47542df6-597a-45b4-ab18-816c4b538265", "amountMinor": 1500 } ], "totalSpentMinor": 4000, "settledUp": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "patch": { "operationId": "groups_update", "tags": [ "Groups" ], "summary": "Update a group", "description": "All fields are optional; group-edit permission is required. Returns the updated detail.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "type": { "type": "string", "enum": [ "trip", "home", "couple", "event", "family", "other" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "simplifyDebts": { "type": "boolean" }, "policy": { "type": "object", "properties": { "addExpense": { "type": "string", "enum": [ "members", "admins" ] }, "editExpense": { "type": "string", "enum": [ "members", "creator", "admins" ] }, "deleteExpense": { "type": "string", "enum": [ "members", "creator", "admins" ] }, "invite": { "type": "string", "enum": [ "members", "admins" ] }, "archive": { "type": "string", "enum": [ "admins", "owner" ] } }, "required": [ "addExpense", "editExpense", "deleteExpense", "invite", "archive" ] } } }, "example": { "name": "Weekend a Napoli" } } } } }, "delete": { "operationId": "groups_delete", "tags": [ "Groups" ], "summary": "Delete a group", "description": "Owner only, and only by sending the group’s exact name in `confirmName`.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmName": { "type": "string" } }, "required": [ "confirmName" ] }, "example": { "confirmName": "Weekend a Roma" } } } } } }, "/api/expenses": { "get": { "operationId": "expenses_list", "tags": [ "Expenses" ], "summary": "List visible expenses", "description": "Paginated (`page`, `limit` up to 100). The response includes `users` with the names of the people mentioned.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "description": "Only expenses of this group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "friendId", "in": "query", "required": false, "description": "Only expenses between you and this friend.", "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "query", "required": false, "description": "Only expenses this person takes part in.", "schema": { "type": "string", "format": "uuid" } }, { "name": "categoryId", "in": "query", "required": false, "description": "Only this category.", "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Text search in description and notes.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "from", "in": "query", "required": false, "description": "Earliest date (YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Latest date (YYYY-MM-DD).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "status", "in": "query", "required": false, "description": "`active` (default), `deleted` or `all`.", "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted", "all" ] } }, { "name": "kind", "in": "query", "required": false, "description": "`expense` or `refund`.", "schema": { "type": "string", "enum": [ "expense", "refund" ] } }, { "name": "page", "in": "query", "required": false, "description": "Page, from 1.", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "limit", "in": "query", "required": false, "description": "Items per page (1–100, default 30).", "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "items": [ { "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14", "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "groupName": "Weekend a Roma", "kind": "expense", "description": "Cena in Trastevere", "notes": null, "amountMinor": 4000, "currency": "EUR", "baseCurrency": "EUR", "fxRate": "1.00000000", "amountBaseMinor": 4000, "category": null, "expenseDate": "2026-10-21", "splitMethod": "equal", "createdBy": "47542df6-597a-45b4-ab18-816c4b538265", "createdAt": "2026-10-21T15:11:20.630Z", "updatedAt": "2026-10-21T15:11:20.630Z", "deletedAt": null, "version": 1, "payments": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "paidMinor": 4000 } ], "splits": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "owedMinor": 2000, "inputValue": null }, { "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "owedMinor": 2000, "inputValue": null } ], "myNetMinor": 2000, "canEdit": true, "canDelete": true } ], "hasMore": false, "page": 1, "users": { "47542df6-597a-45b4-ab18-816c4b538265": { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "avatarUrl": null }, "b93e456c-f17f-4d42-a36f-96f75dad14f3": { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "avatarUrl": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "post": { "operationId": "expenses_create", "tags": [ "Expenses" ], "summary": "Create an expense", "description": "Returns the detail of the created expense. Amounts are always in minor units. Use `clientId` for a safe retry.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "expense": { "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14", "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "groupName": "Weekend a Roma", "kind": "expense", "description": "Cena in Trastevere", "notes": null, "amountMinor": 4000, "currency": "EUR", "baseCurrency": "EUR", "fxRate": "1.00000000", "amountBaseMinor": 4000, "category": null, "expenseDate": "2026-10-21", "splitMethod": "equal", "createdBy": "47542df6-597a-45b4-ab18-816c4b538265", "createdAt": "2026-10-21T15:11:20.630Z", "updatedAt": "2026-10-21T15:11:20.630Z", "deletedAt": null, "version": 1, "payments": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "paidMinor": 4000 } ], "splits": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "owedMinor": 2000, "inputValue": null }, { "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "owedMinor": 2000, "inputValue": null } ], "myNetMinor": 2000, "canEdit": true, "canDelete": true }, "attachments": [], "users": { "47542df6-597a-45b4-ab18-816c4b538265": { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "avatarUrl": null }, "b93e456c-f17f-4d42-a36f-96f75dad14f3": { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "avatarUrl": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Group of the expense; omitted or null for an expense between friends outside a group." }, "description": { "type": "string", "maxLength": 140, "description": "Short description (max 140 characters)." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Optional notes (max 1000 characters)." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "Total amount in minor units (cents): 4000 = 40.00. Must be greater than zero." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code of the currency the expense was paid in (e.g. EUR)." }, "fxRate": { "anyOf": [ { "type": "string", "pattern": "^\\d+([.,]\\d+)?$" }, { "type": "null" } ], "description": "Rate to the group currency, only when the currencies differ and no known rate exists." }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Category (id from GET /api/meta)." }, "expenseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Expense date (YYYY-MM-DD)." }, "splitMethod": { "type": "string", "enum": [ "equal", "exact", "percent", "shares", "adjust", "items" ], "description": "Split method: equal, exact, percent, shares, adjust or items." }, "payments": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "paidMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 } }, "required": [ "userId", "paidMinor" ] }, "description": "Who paid and how much (the sum must equal amountMinor)." }, "participants": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "value": { "type": "integer", "minimum": -9999999999999, "maximum": 9999999999999 } }, "required": [ "userId" ] }, "description": "Who takes part in the split; `value` is used for exact (amount), percent (percentage ×100), shares and adjust." }, "items": { "maxItems": 60, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 }, "userIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name", "amountMinor", "userIds" ] }, "description": "Receipt line items, only with splitMethod=items." }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Client-generated UUID: makes creation idempotent (a second send with the same id does not duplicate the expense)." } }, "required": [ "description", "amountMinor", "currency", "expenseDate", "splitMethod", "payments", "participants" ] }, "example": { "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "description": "Cena in Trastevere", "amountMinor": 4000, "currency": "EUR", "expenseDate": "2026-10-21", "splitMethod": "equal", "payments": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "paidMinor": 4000 } ], "participants": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265" }, { "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3" } ] } } } } } }, "/api/expenses/{id}": { "get": { "operationId": "expenses_get", "tags": [ "Expenses" ], "summary": "Expense detail", "description": "Includes items, refunds, attachment metadata and the revision history.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "expense": { "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14", "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "groupName": "Weekend a Roma", "kind": "expense", "description": "Cena in Trastevere", "notes": null, "amountMinor": 4000, "currency": "EUR", "baseCurrency": "EUR", "fxRate": "1.00000000", "amountBaseMinor": 4000, "category": null, "expenseDate": "2026-10-21", "splitMethod": "equal", "createdBy": "47542df6-597a-45b4-ab18-816c4b538265", "createdAt": "2026-10-21T15:11:20.630Z", "updatedAt": "2026-10-21T15:11:20.630Z", "deletedAt": null, "version": 1, "payments": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "paidMinor": 4000 } ], "splits": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "owedMinor": 2000, "inputValue": null }, { "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "owedMinor": 2000, "inputValue": null } ], "myNetMinor": 2000, "canEdit": true, "canDelete": true, "items": [], "refunds": [], "refundedMinor": 0, "remainingRefundableMinor": 4000 }, "attachments": [], "revisions": [ { "id": "r1…", "version": 1, "changeType": "create", "changedBy": "47542df6-597a-45b4-ab18-816c4b538265", "createdAt": "2026-10-21T15:11:20.630Z" } ], "users": { "47542df6-597a-45b4-ab18-816c4b538265": { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "avatarUrl": null }, "b93e456c-f17f-4d42-a36f-96f75dad14f3": { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "avatarUrl": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "put": { "operationId": "expenses_update", "tags": [ "Expenses" ], "summary": "Update an expense", "description": "Replaces the whole expense (same body as creation, plus an optional `expectedVersion`). Returns the updated detail.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Group of the expense; omitted or null for an expense between friends outside a group." }, "description": { "type": "string", "maxLength": 140, "description": "Short description (max 140 characters)." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Optional notes (max 1000 characters)." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "Total amount in minor units (cents): 4000 = 40.00. Must be greater than zero." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code of the currency the expense was paid in (e.g. EUR)." }, "fxRate": { "anyOf": [ { "type": "string", "pattern": "^\\d+([.,]\\d+)?$" }, { "type": "null" } ], "description": "Rate to the group currency, only when the currencies differ and no known rate exists." }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Category (id from GET /api/meta)." }, "expenseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Expense date (YYYY-MM-DD)." }, "splitMethod": { "type": "string", "enum": [ "equal", "exact", "percent", "shares", "adjust", "items" ], "description": "Split method: equal, exact, percent, shares, adjust or items." }, "payments": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "paidMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 } }, "required": [ "userId", "paidMinor" ] }, "description": "Who paid and how much (the sum must equal amountMinor)." }, "participants": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "value": { "type": "integer", "minimum": -9999999999999, "maximum": 9999999999999 } }, "required": [ "userId" ] }, "description": "Who takes part in the split; `value` is used for exact (amount), percent (percentage ×100), shares and adjust." }, "items": { "maxItems": 60, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 }, "userIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name", "amountMinor", "userIds" ] }, "description": "Receipt line items, only with splitMethod=items." }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Client-generated UUID: makes creation idempotent (a second send with the same id does not duplicate the expense)." }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Version the client read: if the expense changed meanwhile the edit is rejected with 409." } }, "required": [ "description", "amountMinor", "currency", "expenseDate", "splitMethod", "payments", "participants" ] }, "example": { "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "description": "Cena in Trastevere (con mancia)", "amountMinor": 4400, "currency": "EUR", "expenseDate": "2026-10-21", "splitMethod": "equal", "payments": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265", "paidMinor": 4400 } ], "participants": [ { "userId": "47542df6-597a-45b4-ab18-816c4b538265" }, { "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3" } ], "expectedVersion": 1 } } } } }, "delete": { "operationId": "expenses_delete", "tags": [ "Expenses" ], "summary": "Delete an expense", "description": "Soft delete: the expense stays in the history with `deletedAt`.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write" } }, "/api/settlements": { "get": { "operationId": "settlements_list", "tags": [ "Settlements" ], "summary": "List recorded settlements", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "description": "Only settlements of this group.", "schema": { "type": "string", "format": "uuid" } }, { "name": "friendId", "in": "query", "required": false, "description": "Only settlements between you and this friend.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "items": [ { "id": "s1…", "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "fromUserId": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "toUserId": "47542df6-597a-45b4-ab18-816c4b538265", "amountMinor": 500, "currency": "EUR", "method": "cash", "note": null, "settledOn": "2026-10-21", "createdBy": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "canDelete": true } ], "users": { "47542df6-597a-45b4-ab18-816c4b538265": { "id": "47542df6-597a-45b4-ab18-816c4b538265", "name": "Anna", "avatarUrl": null }, "b93e456c-f17f-4d42-a36f-96f75dad14f3": { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "avatarUrl": null } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "post": { "operationId": "settlements_create", "tags": [ "Settlements" ], "summary": "Record a payment between two people", "description": "BillMate is a ledger: this call records a payment that already happened, it does not move money.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "example": { "id": "s1…" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Group of the payment; null for a payment between friends." }, "fromUserId": { "type": "string", "format": "uuid", "description": "Who paid." }, "toUserId": { "type": "string", "format": "uuid", "description": "Who received." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "Amount in minor units, greater than zero." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 currency." }, "method": { "default": "cash", "type": "string", "enum": [ "cash", "bank_transfer", "paypal", "revolut", "satispay", "other" ], "description": "cash, bank_transfer, paypal, revolut, satispay or other (default cash)." }, "note": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "description": "Optional note (max 300 characters)." }, "settledOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Payment date (YYYY-MM-DD)." } }, "required": [ "fromUserId", "toUserId", "amountMinor", "currency", "settledOn" ] }, "example": { "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03", "fromUserId": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "toUserId": "47542df6-597a-45b4-ab18-816c4b538265", "amountMinor": 500, "currency": "EUR", "method": "cash", "settledOn": "2026-10-21" } } } } } }, "/api/settlements/{id}": { "delete": { "operationId": "settlements_delete", "tags": [ "Settlements" ], "summary": "Remove a recorded settlement", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write" } }, "/api/friends": { "get": { "operationId": "friends_list", "tags": [ "Friends" ], "summary": "Friends and friend requests", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "example": { "friends": [ { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "email": "luca@example.com", "avatarUrl": null, "explicit": true, "balances": [ { "currency": "EUR", "amountMinor": 1500 } ] } ], "incoming": [], "outgoing": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "bm_…", "description": "Personal API key: `Authorization: Bearer bm_…`" } }, "responses": { "Unauthorized": { "description": "Missing, invalid, expired or revoked key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "details": {} }, "required": [ "code" ] } }, "required": [ "error" ] } } } }, "Forbidden": { "description": "Read-only key, endpoint not available to keys, or insufficient permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "details": {} }, "required": [ "code" ] } }, "required": [ "error" ] } } } }, "RateLimited": { "description": "Too many requests: retry after `retryAfterSec` seconds", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "details": {} }, "required": [ "code" ] } }, "required": [ "error" ] } } } } } } }