> ## Documentation Index > Fetch the complete documentation index at: https://docs.finta.io/llms.txt > Use this file to discover all available pages before exploring further. # Set a budget > Create or edit the budget for a category or category group, or assign to a credit card's payment envelope, in the default plan unless `plan` names another. `scope: "template"` changes the amount from the current month forward and creates the budget if it has none. `scope: "period"` changes one month and needs an existing budget, except for `accountId`, which takes `scope: "period"` only and creates the envelope's budget on the first assignment. In an envelope plan, `scope: "period"` is the assign action and `amount` is that month's total. The first budget creates the default plan. ## OpenAPI ````yaml /api/v2/openapi.json post /budgets openapi: 3.0.3 info: title: Finta API v2 version: 2.0.0 description: >- DB-backed Finta API for users with storage mode enabled. Requires an API key or an OAuth access token, and an active subscription or free trial. ## Rate limits Rate limits are enforced per user based on subscription plan, separately from MCP. The free trial gets Standard limits, or Pro limits if you're trialing Pro: | Plan | Per minute | Per day | | --- | --- | --- | | Standard | 20 requests | 500 requests | | Pro | 60 requests | 2,000 requests | When a limit is exceeded, the API returns HTTP 429 with `error.code` `RATE_LIMITED` and a human-readable `message`. A `Retry-After` response header is included with the number of seconds until the window resets. servers: - url: https://api.finta.io/v2 description: Production server security: - bearerAuth: [] tags: - name: Me description: Authenticated user - name: Health description: Service health - name: Bank Connections description: Bank connection resources - name: Accounts description: Account and balance history resources - name: Investments description: Securities, holdings, and investment transaction resources - name: Transactions description: Transaction resources - name: Categories description: Transaction category resources - name: Category Groups description: Category group resources - name: Rules description: Transaction rule resources - name: Budgets description: Budget plans, budgets, and budget status paths: /budgets: post: tags: - Budgets summary: Set a budget description: >- Create or edit the budget for a category or category group, or assign to a credit card's payment envelope, in the default plan unless `plan` names another. `scope: "template"` changes the amount from the current month forward and creates the budget if it has none. `scope: "period"` changes one month and needs an existing budget, except for `accountId`, which takes `scope: "period"` only and creates the envelope's budget on the first assignment. In an envelope plan, `scope: "period"` is the assign action and `amount` is that month's total. The first budget creates the default plan. operationId: setBudgetV2 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BudgetSetRequest' responses: '200': description: Edited an existing budget content: application/json: schema: $ref: '#/components/schemas/BudgetSetResponse' '201': description: Created the budget content: application/json: schema: $ref: '#/components/schemas/BudgetSetResponse' '400': description: >- `BAD_REQUEST` for an invalid body, or `INVALID_TARGET`, `INVALID_PERIOD`, `PERIOD_BEFORE_START`, `BUDGET_INACTIVE`, `UNSUPPORTED_CADENCE`, `SNAPSHOT_RANGE_TOO_LONG`, `CATEGORY_NOT_EXPENSE`, or for `accountId`, `ACCOUNT_NOT_CREDIT`, `ACCOUNT_NOT_IN_PLAN`, `METHOD_NOT_ENVELOPE` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '403': description: Storage mode required or subscription inactive content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- `NOT_FOUND`. The plan, budget, category or account does not exist, or budgets are not enabled for this account yet. A bad plan lists the user's plan names in `message`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': $ref: '#/components/responses/RateLimitedResponse' components: schemas: BudgetSetRequest: description: >- Send exactly one of `categoryId`, `categoryGroupId` or, with `scope: "period"`, `accountId`. Fields from the other scope are rejected. oneOf: - type: object additionalProperties: false required: - scope - amount properties: scope: type: string enum: - template categoryId: type: string format: uuid categoryGroupId: type: string format: uuid amount: type: number minimum: 0 description: Dollars, at most 2 decimal places rolloverEnabled: type: boolean targetAmount: type: number minimum: 0 nullable: true description: Savings goal in dollars, or null to clear it targetDate: type: string format: date nullable: true startPeriod: type: string description: 'New budgets only: `current` (default) or YYYY-MM' plan: type: string description: Plan name or id - type: object additionalProperties: false required: - scope - period - amount properties: scope: type: string enum: - period categoryId: type: string format: uuid categoryGroupId: type: string format: uuid accountId: type: string format: uuid description: >- Credit card account, for its payment envelope in an envelope plan period: type: string description: '`current` or YYYY-MM' amount: type: number minimum: 0 description: Dollars, at most 2 decimal places note: type: string maxLength: 500 nullable: true plan: type: string description: Plan name or id BudgetSetResponse: allOf: - $ref: '#/components/schemas/BudgetUpdateResponse' - type: object required: - created - plan properties: created: type: boolean description: True when this call created the budget plan: $ref: '#/components/schemas/BudgetPlan' ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: STORAGE_MODE_REQUIRED message: type: string UnauthorizedResponse: type: object required: - error properties: error: type: string example: Missing or invalid Authorization header BudgetUpdateResponse: type: object required: - budget - periodOverride - snapshot properties: budget: $ref: '#/components/schemas/Budget' periodOverride: type: object nullable: true description: 'Set for `scope: "period"`' required: - budgetId - period - startDate - endDate - plannedAmount - note - source properties: budgetId: type: string format: uuid period: type: string startDate: type: string format: date endDate: type: string format: date plannedAmount: type: number note: type: string nullable: true source: type: string enum: - user_edited - snapshot snapshot: type: object nullable: true description: >- Set for `scope: "template"` when the amount changed: the past months written down at the old amount required: - budgetId - periodsConsidered - rowsWritten - truncated properties: budgetId: type: string format: uuid periodsConsidered: type: integer rowsWritten: type: integer truncated: type: boolean BudgetPlan: type: object required: - id - name - method - accountScope - isDefault properties: id: type: string format: uuid name: type: string method: type: string enum: - standard - envelope accountScope: type: string enum: - All - Selected isDefault: type: boolean Budget: type: object required: - id - planId - targetType - categoryId - categoryGroupId - accountId - amount - rolloverEnabled - targetAmount - targetDate - startPeriod - isActive properties: id: type: string format: uuid planId: type: string format: uuid targetType: type: string enum: - category - category_group - account categoryId: type: string format: uuid nullable: true categoryGroupId: type: string format: uuid nullable: true accountId: type: string format: uuid nullable: true description: The credit card, for a payment envelope amount: type: number description: >- The template amount in dollars. A one-month amount is in `periodOverride`. rolloverEnabled: type: boolean targetAmount: type: number nullable: true targetDate: type: string format: date nullable: true startPeriod: type: string format: date description: First day of the first month the budget applies to isActive: type: boolean responses: RateLimitedResponse: description: Rate limit exceeded headers: Retry-After: description: Seconds until the rate-limit window resets schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Per-minute rate limit exceeded (standard plan) securitySchemes: bearerAuth: type: http scheme: bearer description: >- A Finta API key from API settings, or an OAuth access token issued to an authorized app. Send either as `Authorization: Bearer `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.