{
  "openapi": "3.1.0",
  "info": {
    "title": "Dimesum API",
    "version": "1",
    "description": "Everything you can do with your own groups, bills and balances, from a script, a spreadsheet or an assistant. Authenticate with a developer key from Me > Developer in the app. Money is always an integer in the currency's minor unit, every write takes a client-generated id so a retry never writes twice, and a key acts as you: it sees what you see and nothing more.",
    "contact": {
      "email": "developers@dimesum.com",
      "url": "https://developers.dimesum.com"
    },
    "termsOfService": "https://dimesum.com/terms.html"
  },
  "servers": [
    {
      "url": "https://api.dimesum.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:8080",
      "description": "Local development"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "You"
    },
    {
      "name": "Groups"
    },
    {
      "name": "Expenses"
    },
    {
      "name": "Balances"
    },
    {
      "name": "Settling"
    },
    {
      "name": "Repeats"
    },
    {
      "name": "Capture"
    },
    {
      "name": "Activity"
    },
    {
      "name": "Insights"
    },
    {
      "name": "People"
    },
    {
      "name": "Rates"
    },
    {
      "name": "Developer"
    }
  ],
  "paths": {
    "/v1/me": {
      "get": {
        "summary": "Who you are",
        "description": "The account the key belongs to.",
        "tags": [
          "You"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Me"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read"
      }
    },
    "/v1/me/balances": {
      "get": {
        "summary": "Balances across every group",
        "description": "Every group you are in, with each member's balance per currency. Fold it by person (user_id) to answer \"who owes me\"; never add across currencies.",
        "tags": [
          "Balances"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeBalances"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "From next_cursor."
          }
        ]
      }
    },
    "/v1/me/activity": {
      "get": {
        "summary": "Your activity feed",
        "description": "What happened across your groups, newest last, as a delta from a cursor.",
        "tags": [
          "Activity"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "A cursor from the previous read."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Up to 500."
          }
        ]
      }
    },
    "/v1/me/insights": {
      "get": {
        "summary": "Your spending insights",
        "description": "Your share of spending for a month and the year around it: by group, by category (by_category), by day, by week, what repeats (fixed_months).",
        "tags": [
          "Insights"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "YYYY-MM; this month by default."
          }
        ]
      }
    },
    "/v1/people": {
      "get": {
        "summary": "People you keep",
        "description": "People added by their code or phone number, outside any group.",
        "tags": [
          "People"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "people": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Person"
                      }
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read"
      }
    },
    "/v1/groups": {
      "get": {
        "summary": "List groups",
        "description": "Every group you are in, with your position in each.",
        "tags": [
          "Groups"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GroupRow"
                      }
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read"
      },
      "post": {
        "summary": "Create a group",
        "description": "You are its first member and owner.",
        "tags": [
          "Groups"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupDetail"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 60
                  },
                  "default_currency": {
                    "type": "string",
                    "description": "ISO 4217 code.",
                    "pattern": "^[A-Z]{3}$",
                    "example": "INR"
                  },
                  "timezone": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/groups/{groupID}": {
      "get": {
        "summary": "Get a group",
        "description": "Members (with member ids), currency and settings.",
        "tags": [
          "Groups"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GroupDetail"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/members": {
      "post": {
        "summary": "Add a kept place",
        "description": "A member without an account (yet), so bills can include them. Offer it to an account with offer_user_id; they accept in their inbox. Refused with 403 offer_not_connected unless you share a group with that account or keep each other in People.",
        "tags": [
          "Groups"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Member"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "id",
                  "display_name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
                  },
                  "display_name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string",
                    "description": "E.164"
                  },
                  "offer_user_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/balances": {
      "get": {
        "summary": "Group balances",
        "description": "Each member's balance per currency.",
        "tags": [
          "Balances"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balances"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/activity": {
      "get": {
        "summary": "A group's activity feed",
        "description": "Bills, edits, payments and members joining, as a delta from a cursor.",
        "tags": [
          "Activity"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Cursor."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "Up to 500."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/insights": {
      "get": {
        "summary": "Group insights",
        "description": "The group's spending for a month: totals, by member, by day, by category (by_category, my_by_category; category null is the uncategorised bucket).",
        "tags": [
          "Insights"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "YYYY-MM."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/editors": {
      "get": {
        "summary": "Who can edit bills",
        "description": "The group's editor policy. Anyone may always change a bill they added.",
        "tags": [
          "Groups"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Editors"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/expenses": {
      "get": {
        "summary": "List bills",
        "description": "Newest first, paged. Deleted bills stay in the list with deleted=true.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExpensePage"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            },
            "description": "1 to 100, 20 by default."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "From next_cursor."
          }
        ]
      },
      "post": {
        "summary": "Add a bill",
        "description": "Split equally among everyone unless you say otherwise; you paid unless payers says otherwise.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExpenseCreate"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/expenses/{expenseID}": {
      "get": {
        "summary": "Get a bill",
        "description": "With its split inputs, version and can_edit for you.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      },
      "patch": {
        "summary": "Edit a bill",
        "description": "Restate the whole bill from the version you read. Refused with 403 not_editor unless it is your bill or the group lets you edit others'.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExpenseAmend"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      },
      "delete": {
        "summary": "Delete a bill",
        "description": "A tombstone: the ledger reverses it and the history keeps it.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExpenseDelete"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/expenses/{expenseID}/revisions": {
      "get": {
        "summary": "A bill's history",
        "description": "One snapshot per version.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "revisions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Revision"
                      }
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/expenses/{expenseID}/comments": {
      "get": {
        "summary": "A bill's comments",
        "description": "Oldest first; deleted ones stay as tombstones.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "comments": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Comment"
                      }
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      },
      "post": {
        "summary": "Comment on a bill",
        "description": "Up to 30 per member per hour, 200 per bill.",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comment"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CommentCreate"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/expenses/{expenseID}/fx-rate": {
      "put": {
        "summary": "Set a bill's rate",
        "description": "For a bill in another currency: group currency per unit, e.g. \"0.5624\".",
        "tags": [
          "Expenses"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "rate"
                ],
                "properties": {
                  "rate": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "expenseID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The bill's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/recurring": {
      "get": {
        "summary": "Repeats",
        "description": "The group's standing instructions (rent, subscriptions).",
        "tags": [
          "Repeats"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      },
      "post": {
        "summary": "Create a repeat",
        "description": "Posts an ordinary bill on schedule; each occurrence is idempotent per period.",
        "tags": [
          "Repeats"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RecurringCreate"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/settlements": {
      "get": {
        "summary": "Payments",
        "description": "Newest first, paged.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "settlements": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Settlement"
                      }
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "From next_cursor."
          }
        ]
      },
      "post": {
        "summary": "Record a payment",
        "description": "Something you paid in your own app or in cash. Any positive amount: more than you owe leaves them owing you the difference.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settlement"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettlementCreate"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/settlements/{settlementID}/confirm": {
      "post": {
        "summary": "Confirm a payment",
        "description": "As the person paid.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settlement"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "settlementID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The payment's id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/settlements/{settlementID}/dispute": {
      "post": {
        "summary": "Dispute a payment",
        "description": "As the person paid: the money did not arrive. The payment is reversed.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Settlement"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          },
          {
            "name": "settlementID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The payment's id."
          }
        ]
      }
    },
    "/v1/settlement-batches/{batchID}": {
      "get": {
        "summary": "One payment across groups",
        "description": "Every leg of a transfer that cleared several groups, in the groups you share.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementBatch"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "batchID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The transfer's batch id."
          }
        ]
      }
    },
    "/v1/settlement-batches/{batchID}/confirm": {
      "post": {
        "summary": "Confirm a payment across groups",
        "description": "As the other person: confirms every leg you are the counterparty of, once.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementBatch"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "batchID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The transfer's batch id."
          }
        ]
      }
    },
    "/v1/settlement-batches/{batchID}/dispute": {
      "post": {
        "summary": "Dispute a payment across groups",
        "description": "As the other person: the money did not arrive. Every leg is reversed.",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SettlementBatch"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "batchID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The transfer's batch id."
          }
        ]
      }
    },
    "/v1/groups/{groupID}/write-offs": {
      "get": {
        "summary": "Forgiven debts",
        "description": "Debts a creditor forgave (write-offs are made in the app).",
        "tags": [
          "Settling"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Loose"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "groupID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The group's id."
          }
        ]
      }
    },
    "/v1/captures": {
      "post": {
        "summary": "Read a line into a draft",
        "description": "A sentence in, a suggestion out, never a posted bill: a person (or your script) confirms it. With no parser configured the suggestion still arrives: the line is its name and the amount is left for a person to fill.",
        "tags": [
          "Capture"
        ],
        "responses": {
          "201": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Suggestion"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CaptureCreate"
              }
            }
          }
        }
      }
    },
    "/v1/suggestions": {
      "get": {
        "summary": "Suggestions",
        "description": "Drafts waiting to be confirmed.",
        "tags": [
          "Capture"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "suggestions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Suggestion"
                      }
                    }
                  }
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read"
      }
    },
    "/v1/suggestions/{suggestionID}": {
      "get": {
        "summary": "A suggestion",
        "description": "",
        "tags": [
          "Capture"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Suggestion"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "suggestionID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The suggestion's id."
          }
        ]
      }
    },
    "/v1/suggestions/{suggestionID}/confirm": {
      "post": {
        "summary": "Confirm a suggestion",
        "description": "Posts it as a bill, with anything you correct. Idempotent: the bill's id comes from the suggestion's.",
        "tags": [
          "Capture"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Expense"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SuggestionConfirm"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "suggestionID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The suggestion's id."
          }
        ]
      }
    },
    "/v1/suggestions/{suggestionID}/dismiss": {
      "post": {
        "summary": "Dismiss a suggestion",
        "description": "",
        "tags": [
          "Capture"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Suggestion"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "suggestionID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The suggestion's id."
          }
        ]
      }
    },
    "/v1/fx/quote": {
      "get": {
        "summary": "A market rate",
        "description": "The latest published rate between two currencies, for reference.",
        "tags": [
          "Rates"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FXQuote"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO code."
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "ISO code."
          }
        ]
      }
    },
    "/v1/developer/key": {
      "get": {
        "summary": "This key",
        "description": "Which key is calling, its scopes, its limits and its recent requests.",
        "tags": [
          "Developer"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperKey"
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read"
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP endpoint",
        "description": "Model Context Protocol over Streamable HTTP (JSON-RPC 2.0, JSON responses). Methods: initialize, tools/list, tools/call, ping. See the MCP guide for the tools.",
        "tags": [
          "Developer"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "4XX": {
            "description": "A refusal with a stable code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-scope": "read",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": true,
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "enum": [
                      "2.0"
                    ]
                  },
                  "id": {},
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "dms_live_…",
        "description": "Authorization: Bearer dms_live_… — one key per account, read or read-and-write."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable, machine-readable reason, e.g. not_found, api_key_read_only, not_editor."
              },
              "message": {
                "type": "string",
                "description": "A sentence for a person."
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Money": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "net_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          }
        }
      },
      "Me": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "display_name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "timezone": {
            "type": "string",
            "example": "Asia/Kolkata"
          },
          "preferred_currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "avatar_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "GroupRow": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "default_currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "kind": {
            "type": "string",
            "enum": [
              "GROUP",
              "QUICK"
            ]
          },
          "member_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "read_only": {
            "type": "boolean"
          },
          "archived": {
            "type": "boolean",
            "description": "You archived it in the app: hidden from your own home screen and pickers, nobody else's. Its money still counts everywhere."
          },
          "square": {
            "type": "boolean",
            "description": "True only when every member is at zero in every currency."
          },
          "your_position": {
            "type": "array",
            "description": "Your net in each currency: positive means the group owes you.",
            "items": {
              "$ref": "#/components/schemas/Money"
            }
          }
        }
      },
      "Member": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "The member id. Bills and payments name people by this."
          },
          "display_name": {
            "type": "string"
          },
          "is_ghost": {
            "type": "boolean",
            "description": "A kept place: somebody without an account (yet)."
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "description": "The account behind the member, when there is one."
          },
          "avatar_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "GroupDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "default_currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "timezone": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "my_member_id": {
            "type": "string",
            "format": "uuid",
            "description": "Your own member id in this group."
          },
          "owner_member_id": {
            "type": "string",
            "format": "uuid"
          },
          "read_only": {
            "type": "boolean"
          },
          "members": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Member"
            }
          }
        }
      },
      "Split": {
        "type": "object",
        "properties": {
          "member_id": {
            "type": "string",
            "format": "uuid"
          },
          "share_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "paid_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          }
        }
      },
      "Location": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "lat": {
            "type": "number"
          },
          "lng": {
            "type": "number"
          }
        }
      },
      "Expense": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": "string",
            "format": "uuid"
          },
          "version": {
            "type": "integer",
            "description": "Bumps on every edit; an edit must name the version it read."
          },
          "deleted": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "group_currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "fx_rate": {
            "type": "string",
            "description": "Group currency per unit of this bill's currency, as a decimal string."
          },
          "amount_group_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "needs_fx_rate": {
            "type": "boolean"
          },
          "display_currency": {
            "type": "string",
            "description": "The group's currency this bill is READ in. Present on a bill in another currency when a market rate was available for its day."
          },
          "display_rate": {
            "type": "string",
            "description": "The market rate for the bill's day: display_currency per unit of this bill's currency, as a decimal string. For reading only (\"about ₹4,750\"): it never changes a balance and is not fx_rate."
          },
          "display_rate_on": {
            "type": "string",
            "description": "The date the rate was published for.",
            "format": "date"
          },
          "display_rate_source": {
            "type": "string",
            "description": "Who published the rate, e.g. ECB."
          },
          "split_type": {
            "type": "string",
            "enum": [
              "EQUAL",
              "EXACT",
              "PERCENT",
              "SHARES"
            ]
          },
          "occurred_on": {
            "type": "string",
            "description": "A calendar date, YYYY-MM-DD.",
            "format": "date"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "created_by_member_id": {
            "type": "string",
            "format": "uuid"
          },
          "read_only": {
            "type": "boolean"
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "What the bill was for, from a fixed list. Null: uncategorised.",
            "enum": [
              "food_dining",
              "groceries",
              "transport",
              "travel",
              "stay",
              "rent",
              "utilities",
              "entertainment",
              "shopping",
              "other",
              null
            ]
          },
          "category_source": {
            "type": [
              "string",
              "null"
            ],
            "description": "USER: a person chose it, and it is never overwritten. AI: labelled by the model after the bill was added, replaced by a person's choice or by a new label when the title changes. Null: nobody has chosen. USER with a null category: somebody cleared it on purpose.",
            "enum": [
              "USER",
              "AI",
              null
            ]
          },
          "can_edit": {
            "type": "boolean",
            "description": "On a single bill: whether YOU may change it (its author always; others as the group's editor policy allows)."
          },
          "splits": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Split"
            }
          },
          "items": {
            "type": "array",
            "description": "On a single bill by item: its lines.",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "pools": {
            "type": "array",
            "description": "On a single bill by item: its tax, tip, fees and discounts, in order.",
            "items": {
              "$ref": "#/components/schemas/Pool"
            }
          }
        }
      },
      "ExpensePage": {
        "type": "object",
        "properties": {
          "expenses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Expense"
            }
          },
          "next_cursor": {
            "type": "string",
            "description": "Pass as ?cursor= for the next page; absent on the last."
          }
        }
      },
      "Payer": {
        "type": "object",
        "properties": {
          "member_id": {
            "type": "string",
            "format": "uuid"
          },
          "paid_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          }
        },
        "required": [
          "member_id",
          "paid_minor"
        ]
      },
      "MemberValue": {
        "type": "object",
        "properties": {
          "member_id": {
            "type": "string",
            "format": "uuid"
          },
          "value": {
            "type": "integer"
          }
        },
        "required": [
          "member_id",
          "value"
        ]
      },
      "Item": {
        "type": "object",
        "required": [
          "amount_minor"
        ],
        "description": "One line of a bill by item.",
        "properties": {
          "description": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "assignees": {
            "type": "array",
            "description": "Who had it. Empty: shared by everyone in the bill, by its split_type.",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "shares": {
            "type": "array",
            "description": "Optional: an unequal split of this line over its assignees, in minor units.",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          }
        }
      },
      "Pool": {
        "type": "object",
        "required": [
          "kind"
        ],
        "description": "Tax, tip, a fee or a discount on a bill by item, applied in list order and shared by what each person had. State amount_minor OR rate_bp, not both.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "TAX",
              "TIP",
              "FEE",
              "DISCOUNT"
            ]
          },
          "label": {
            "type": "string",
            "description": "The bill's own word for it, e.g. GST."
          },
          "amount_minor": {
            "type": "integer",
            "description": "A flat amount, never negative: a DISCOUNT is taken off by its kind. 0 with a rate."
          },
          "rate_bp": {
            "type": "integer",
            "description": "A percentage in basis points (500 = 5%), worked out on the items plus every pool before it in the list except a TIP, so tax after a service charge is charged on that too, and nothing is charged on a tip."
          }
        }
      },
      "ExpenseCreate": {
        "type": "object",
        "required": [
          "id",
          "description"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "description": {
            "type": "string",
            "maxLength": 120
          },
          "amount_minor": {
            "type": "integer",
            "description": "In the currency's minor unit. Required unless the bill is by item (items)."
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "split_type": {
            "type": "string",
            "enum": [
              "EQUAL",
              "EXACT",
              "PERCENT",
              "SHARES"
            ],
            "default": "EQUAL"
          },
          "participants": {
            "type": "array",
            "description": "Member ids who share it. Everyone in the group when left out.",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "payers": {
            "type": "array",
            "description": "Who paid how much; must sum to amount_minor. You, paying all of it, when left out.",
            "items": {
              "$ref": "#/components/schemas/Payer"
            }
          },
          "shares": {
            "type": "array",
            "description": "EXACT: each person's amount in minor units.",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          },
          "percents": {
            "type": "array",
            "description": "PERCENT: basis points (100% = 10000).",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          },
          "weights": {
            "type": "array",
            "description": "SHARES: relative weights.",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          },
          "items": {
            "type": "array",
            "description": "A bill by item. The total is then the lines plus the pools, so amount_minor may be left out; if sent, it must agree.",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "pools": {
            "type": "array",
            "description": "With items: tax, tip, fees and discounts, in the order the bill prints them.",
            "items": {
              "$ref": "#/components/schemas/Pool"
            }
          },
          "occurred_on": {
            "type": "string",
            "description": "A calendar date, YYYY-MM-DD.",
            "format": "date"
          },
          "fx_rate": {
            "type": "string",
            "description": "For a bill converted into another currency: convert_to's currency (the group's when convert_to is left out) per unit."
          },
          "convert_to": {
            "type": "string",
            "description": "The currency this bill is converted into for the group's totals. Left out, the bill stays in its own currency (the one you sent) and never needs a rate; with an fx_rate and no convert_to, the group's currency. Send the group's currency to convert it."
          },
          "location": {
            "$ref": "#/components/schemas/Location"
          },
          "category": {
            "type": "string",
            "description": "Optional. Left out, the bill is labelled for you shortly after it is added; set, it is yours and is never overwritten.",
            "enum": [
              "food_dining",
              "groceries",
              "transport",
              "travel",
              "stay",
              "rent",
              "utilities",
              "entertainment",
              "shopping",
              "other"
            ]
          }
        }
      },
      "ExpenseAmend": {
        "type": "object",
        "required": [
          "revision_id",
          "base_version",
          "description",
          "amount_minor",
          "split_type",
          "participants"
        ],
        "description": "An edit restates the whole bill: a typo fix must not silently change who shares it.",
        "properties": {
          "revision_id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "base_version": {
            "type": "integer",
            "description": "The version you read. A stale one is refused (409 stale_version)."
          },
          "description": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "occurred_on": {
            "type": "string",
            "description": "A calendar date, YYYY-MM-DD.",
            "format": "date"
          },
          "fx_rate": {
            "type": "string",
            "description": "As on create."
          },
          "convert_to": {
            "type": "string",
            "description": "The currency this bill is converted into for the group's totals. Left out, the bill stays in its own currency (the one you sent) and never needs a rate; with an fx_rate and no convert_to, the group's currency. Send the group's currency to convert it."
          },
          "split_type": {
            "type": "string",
            "enum": [
              "EQUAL",
              "EXACT",
              "PERCENT",
              "SHARES"
            ]
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "payers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Payer"
            }
          },
          "shares": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          },
          "percents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          },
          "weights": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberValue"
            }
          },
          "items": {
            "type": "array",
            "description": "Restate the lines, or the bill stops being by item.",
            "items": {
              "$ref": "#/components/schemas/Item"
            }
          },
          "pools": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pool"
            }
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "description": "The one field an edit may leave out: absent or null keeps the bill's category; \"\" clears it for good; a value sets it as yours.",
            "enum": [
              "food_dining",
              "groceries",
              "transport",
              "travel",
              "stay",
              "rent",
              "utilities",
              "entertainment",
              "shopping",
              "other",
              "",
              null
            ]
          }
        }
      },
      "ExpenseDelete": {
        "type": "object",
        "required": [
          "revision_id",
          "base_version"
        ],
        "properties": {
          "revision_id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "base_version": {
            "type": "integer"
          }
        }
      },
      "Revision": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "version": {
            "type": "integer"
          },
          "action": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Comment": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "author_member_id": {
            "type": "string",
            "format": "uuid"
          },
          "body": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "edited": {
            "type": "boolean"
          },
          "deleted": {
            "type": "boolean"
          }
        }
      },
      "CommentCreate": {
        "type": "object",
        "required": [
          "id",
          "body"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "body": {
            "type": "string",
            "maxLength": 1000
          }
        }
      },
      "CurrencyBalance": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "balance_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          }
        }
      },
      "MemberBalance": {
        "type": "object",
        "properties": {
          "member_id": {
            "type": "string",
            "format": "uuid"
          },
          "display_name": {
            "type": "string"
          },
          "is_ghost": {
            "type": "boolean"
          },
          "balances": {
            "type": "array",
            "description": "Per currency. Positive: the group owes this member; negative: they owe the group.",
            "items": {
              "$ref": "#/components/schemas/CurrencyBalance"
            }
          }
        }
      },
      "Balances": {
        "type": "object",
        "properties": {
          "balances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MemberBalance"
            }
          }
        }
      },
      "MeBalances": {
        "type": "object",
        "description": "Every group you are in with its members' balances, paged over your groups.",
        "properties": {
          "groups": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true,
              "properties": {
                "group_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "default_currency": {
                  "type": "string",
                  "description": "ISO 4217 code.",
                  "pattern": "^[A-Z]{3}$",
                  "example": "INR"
                },
                "my_member_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "members": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/MemberBalance"
                  }
                }
              }
            }
          },
          "next_cursor": {
            "type": "string"
          }
        }
      },
      "Settlement": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "from_member_id": {
            "type": "string",
            "format": "uuid"
          },
          "to_member_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "status": {
            "type": "string",
            "enum": [
              "RECORDED",
              "POSTED",
              "CONFIRMED",
              "REVERSED"
            ]
          },
          "method": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "batch_id": {
            "type": "string",
            "format": "uuid",
            "description": "Set when this payment is one leg of a transfer that cleared several groups."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "SettlementBatch": {
        "type": "object",
        "description": "One transfer that cleared several groups: one settlement per group, the legs you can see.",
        "properties": {
          "batch_id": {
            "type": "string",
            "format": "uuid"
          },
          "legs": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "group_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "group_name": {
                  "type": "string"
                },
                "amount_minor": {
                  "type": "integer",
                  "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
                  "format": "int64"
                },
                "currency": {
                  "type": "string",
                  "description": "ISO 4217 code.",
                  "pattern": "^[A-Z]{3}$",
                  "example": "INR"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "RECORDED",
                    "POSTED",
                    "CONFIRMED",
                    "REVERSED"
                  ]
                },
                "from": {
                  "type": "object",
                  "properties": {
                    "member_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "display_name": {
                      "type": "string"
                    }
                  }
                },
                "to": {
                  "type": "object",
                  "properties": {
                    "member_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "user_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "display_name": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "SettlementCreate": {
        "type": "object",
        "required": [
          "id",
          "from_member_id",
          "to_member_id",
          "amount_minor"
        ],
        "description": "Records a payment that already happened in a bank or payment app. Dimesum holds no money; the other person confirms or disputes, and silence confirms after 48 hours.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "from_member_id": {
            "type": "string",
            "format": "uuid",
            "description": "Must be your own member id."
          },
          "to_member_id": {
            "type": "string",
            "format": "uuid"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "method": {
            "type": "string",
            "enum": [
              "UPI",
              "CASH",
              "OTHER",
              "PAYPAL",
              "VENMO",
              "CASHAPP",
              "WISE",
              "REVOLUT",
              "ZELLE",
              "PAYNOW",
              "PIX",
              "IBAN",
              "BANK"
            ]
          },
          "reference": {
            "type": "string",
            "description": "The payment app's reference, for the other person to find."
          },
          "note": {
            "type": "string"
          },
          "batch_id": {
            "type": "string",
            "format": "uuid",
            "description": "Optional. The same id on every leg of one transfer that clears several groups; every leg must be between the same two people, in one currency (400 batch_mismatch otherwise)."
          }
        }
      },
      "RecurringCreate": {
        "type": "object",
        "required": [
          "id",
          "description",
          "amount_minor",
          "freq"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "description": {
            "type": "string"
          },
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "split_type": {
            "type": "string"
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "freq": {
            "type": "string",
            "enum": [
              "DAILY",
              "WEEKLY",
              "MONTHLY"
            ]
          },
          "day_of_month": {
            "type": "integer",
            "minimum": 1,
            "maximum": 28
          },
          "weekday": {
            "type": "integer",
            "minimum": 0,
            "maximum": 6
          },
          "start_on": {
            "type": "string",
            "description": "A calendar date, YYYY-MM-DD.",
            "format": "date"
          },
          "source_expense_id": {
            "type": "string",
            "format": "uuid",
            "description": "The bill this repeats, when switched on from one."
          }
        }
      },
      "CaptureCreate": {
        "type": "object",
        "required": [
          "id",
          "group_id",
          "text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "A UUID YOU generate (v7 recommended). It is the idempotency key: repeating the request with the same id replays it (200) instead of writing twice; the same id with different content is 409."
          },
          "group_id": {
            "type": "string",
            "format": "uuid"
          },
          "text": {
            "type": "string",
            "description": "A line in plain words, e.g. \"dinner 1200 with Ravi and Priya, I paid\".",
            "maxLength": 2000
          }
        }
      },
      "Suggestion": {
        "type": "object",
        "additionalProperties": true,
        "description": "A capture read into a draft. Nothing is posted until it is confirmed.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "group_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "PENDING",
              "CONFIRMED",
              "DISMISSED"
            ]
          },
          "description": {
            "type": "string"
          },
          "amount_minor": {
            "type": [
              "integer",
              "null"
            ]
          },
          "currency": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "text": {
            "type": "string"
          }
        }
      },
      "SuggestionConfirm": {
        "type": "object",
        "properties": {
          "amount_minor": {
            "type": "integer",
            "description": "Money in the currency's MINOR unit (paise for INR, cents for USD, yen for JPY). Never a float.",
            "format": "int64"
          },
          "description": {
            "type": "string"
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        }
      },
      "Person": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "display_name": {
            "type": "string"
          },
          "avatar_url": {
            "type": "string"
          },
          "via": {
            "type": "string",
            "enum": [
              "CODE",
              "PHONE"
            ]
          },
          "since": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Editors": {
        "type": "object",
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "OWNER",
              "EVERYONE"
            ],
            "description": "OWNER: the owner and member_ids may change anybody's bill. EVERYONE: all members may."
          },
          "member_ids": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          }
        }
      },
      "FXQuote": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "from": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "to": {
            "type": "string",
            "description": "ISO 4217 code.",
            "pattern": "^[A-Z]{3}$",
            "example": "INR"
          },
          "rate": {
            "type": "string"
          },
          "as_of": {
            "type": "string",
            "description": "A calendar date, YYYY-MM-DD.",
            "format": "date"
          }
        }
      },
      "DeveloperKey": {
        "type": "object",
        "properties": {
          "key": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "prefix": {
                "type": "string",
                "example": "dms_live_Ab3x"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "read",
                    "write"
                  ]
                }
              },
              "enabled": {
                "type": "boolean"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "last_used_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "user_id": {
            "type": "string",
            "format": "uuid"
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "per_second": {
                "type": "number"
              },
              "burst": {
                "type": "integer"
              }
            }
          },
          "requests": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "at": {
                  "type": "string",
                  "format": "date-time"
                },
                "method": {
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "status": {
                  "type": "integer"
                },
                "duration_ms": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "Loose": {
        "type": "object",
        "additionalProperties": true,
        "description": "A report object; see the guide for its fields."
      }
    }
  }
}