Finero API context API

openapi: 3.2.0
info:
  title: Finero Public API context API
  version: 1.0.0
  description: 'Tenant-scoped public API for Finero — AR / cash-flow automation. Authenticate every request with `Authorization: Bearer ` (keys are created in Settings → API and are tenant-owned). All data belongs to the key''s tenant; no request input can address another tenant. Two permissions exist: **admin** keys can call every operation; **readonly** keys only operations without side effects (`x-permission: readonly`). Lists are cursor-paginated (limit 1–100, follow pagination.next_cursor). Request bodies are capped at 64 KiB. Rate limits: 120/min per key and 600/min per tenant, in fixed windows of 60 s and 60 s. The per-tenant budget is ONE budget per workspace, shared by all its API keys AND its MCP agent connections (each agent connection has its own per-credential limit, the key''s). Heavy operations (`x-heavy: true`: summarizeAging, listCustomerAging, listAgingInstallments, summarizeInvoices) read the whole book on every call and also count against 10 per 10 seconds per tenant (60 a minute, in a short window so they cannot arrive in a large burst). EVERY response that reached the limiter carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds until the window resets) and `RateLimit-Policy` (every quota that applies to the operation — the heavy one too on a heavy operation; static per operation), plus the same figures as the newer combined `RateLimit` field. Pace against them rather than waiting to be refused. The triple describes whichever quota is CLOSEST TO REFUSING (on a 429, the one that refused), so a key that is fine may still show little headroom when the tenant is busy. The counters are shared server-side, not per-instance, so the numbers are exact rather than approximate. Requests rejected BEFORE the limiter — unknown path, wrong method, oversized body, missing/invalid/revoked credentials, a workspace without API access — consume no quota and carry no rate-limit fields. 429 adds `Retry-After` in seconds (RFC 9110); waiting that long is enough, and retrying sooner is refused again. Missing and invalid credentials are limited separately per source IP; that quota is deliberately not published. The windows are FIXED rather than sliding, so a burst spanning a boundary can pass up to twice the limit before being refused — do not treat the limit as a hard ceiling over less than two windows. `RateLimit-Remaining` RISES when a window rolls, for the same reason; an increase is the quota refilling, not an error. Watch `RateLimit-Reset` jump upward to tell a roll from a miscount. A 503 is not the limiter: under extreme concurrency the platform sheds load before the request reaches Finero, so it carries neither rate-limit fields nor Retry-After. Back off and retry. Decimal money amounts are exact strings (never floats); *_minor amounts are integers in the currency''s minor unit. Timestamps are ISO 8601 UTC. **There is a second way in.** This API is for systems and unattended automation, authenticated by a tenant API key that acts as the WORKSPACE. If instead a person is present and connecting an AI assistant to their own workspace, use the Finero MCP server at `https://app.getfinero.com/mcp` — Model Context Protocol over the Streamable HTTP transport (JSON-RPC 2.0, `MCP-Protocol-Version` 2026-07-28, 2025-11-25), authorized with OAuth 2.1 so the session acts as THAT PERSON. Its `server.json` manifest — the MCP registry''s published format — is at `https://app.getfinero.com/mcp/server.json`. It is read-mostly — 24 tools (list_tasks, dismiss_task, summarize_aging, list_customer_aging, list_aging_installments, list_invoices, summarize_invoices, get_invoice, list_payment_integrations, list_payments, list_workflows, list_workflow_executions, list_erp_connections, list_sync_runs, get_sync_run, start_erp_sync, list_payment_links, get_payment_link, create_payment_links, list_scheduled_emails, update_scheduled_email, delete_scheduled_email, push_payment_receipts, deactivate_payment_link).'
servers:
- url: https://api.getfinero.com/functions/v1/api
security:
- apiKey: []
tags:
- name: API context
paths:
  /v1/me:
    get:
      operationId: getApiContext
      summary: Identify the calling API key
      description: 'Returns the tenant and key metadata for the presented credential. Useful as a connectivity/permission check before other calls. No side effects.


        Available to **admin and readonly** API keys (no side effects).'
      tags:
      - API context
      security:
      - apiKey: []
      x-permission: readonly
      x-side-effects: false
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  tenant_id:
                    type: string
                    description: The tenant this API key belongs to. All data is scoped to it.
                    format: uuid
                  tenant_name:
                    type: string
                    description: Tenant display name.
                  api_key:
                    type: object
                    properties:
                      id:
                        type: string
                        description: API key id.
                        format: uuid
                      name:
                        type: string
                        description: Key name given at creation.
                      permission:
                        type: string
                        description: admin can call every operation; readonly only side-effect-free ones.
                        enum:
                        - admin
                        - readonly
                      created_at:
                        type: string
                        description: Key creation time (ISO 8601 UTC).
                        format: date-time
                      last_used_at:
                        type:
                        - string
                        - 'null'
                        description: The key's previous recorded use, before this request (recorded at most once a minute); null if never used (ISO 8601 UTC).
                        format: date-time
                    required:
                    - id
                    - name
                    - permission
                    - created_at
                    - last_used_at
                    additionalProperties: false
                required:
                - tenant_id
                - tenant_name
                - api_key
                additionalProperties: false
              example:
                tenant_id: 5b0f6a7e-2f5d-4d24-9e6b-3c1a2b4d5e6f
                tenant_name: Acme Industries
                api_key:
                  id: 4d3c2b1a-0f9e-48d7-b6c5-a4b3c2d1e0f9
                  name: Zapier integration
                  permission: readonly
                  created_at: '2026-07-01T08:00:00+00:00'
                  last_used_at: '2026-07-14T06:59:31+00:00'
        '400':
          description: '`validation_failed` — The request failed schema validation. See error.details for field messages.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`invalid_credentials` — The credential is malformed or does not match an active key. The response never reveals whether a key identifier exists. `missing_credentials` — No Authorization: Bearer header was sent. `revoked_credentials` — The presented key was revoked. Create a new key in Settings → API.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`feature_unavailable` — The tenant''s tier does not currently include API access. Feature rollout flags cannot grant this entitlement. `permission_denied` — The key''s permission does not allow this operation (readonly keys cannot call admin-only operations).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`not_found` — No such resource in YOUR tenant. Ids belonging to another tenant are indistinguishable from missing ones.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '`rate_limit_exceeded` — Too many requests — for this key, for the workspace (one budget shared by all its API keys and MCP agent connections), or, on a heavy operation, for the workspace''s heavy budget. Honor the Retry-After header (seconds) before retrying — waiting that long is enough. The RateLimit-* fields on every response say how much headroom is left before this happens; pace against them instead of retrying into a refusal.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: '`internal_error` — Unexpected server error. Safe to retry with the same Idempotency-Key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      additionalProperties: false
      properties:
        error:
          type: object
          required:
          - code
          - message
          - request_id
          additionalProperties: false
          properties:
            code:
              type: string
              description: Stable machine-readable error code.
              enum:
              - missing_credentials
              - invalid_credentials
              - revoked_credentials
              - feature_unavailable
              - permission_denied
              - not_found
              - invalid_cursor
              - validation_failed
              - conflict
              - link_already_covered
              - link_not_withdrawable
              - payment_link_deactivated
              - idempotency_key_required
              - idempotency_conflict
              - rate_limit_exceeded
              - payload_too_large
              - method_not_allowed
              - installment_not_collectible
              - amount_exceeds_available
              - sync_disabled
              - connection_disconnected
              - integration_unavailable
              - currency_not_supported
              - internal_error
            message:
              type: string
              description: Human-readable explanation.
            request_id:
              type: string
              description: Echo of X-Request-Id — include it when reporting problems.
            details:
              type: array
              description: Field-level validation messages (validation_failed only).
              items:
                type: object
                required:
                - field
                - message
                properties:
                  field:
                    type: string
                  message:
                    type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A Finero API key (`fnr_…`), created by a tenant admin in Settings → API. Sent as `Authorization: Bearer fnr_…`. Never place keys in URLs.'
      x-permissions:
        supported:
        - admin
        - readonly
        operationField: x-permission
        description: 'Each operation declares the LEAST key permission that may call it in `x-permission`. An `admin` key satisfies every operation; a `readonly` key satisfies only operations whose `x-permission` is `readonly`. The router enforces this from the same classification this document is generated from — the check is never inferred from the HTTP method. These are key PERMISSIONS, not OAuth scopes: this scheme is HTTP bearer, and OpenAPI declares `scopes` only on `oauth2`/`openIdConnect` schemes. Finero''s OAuth surface is the MCP server, which publishes RFC 9728 protected-resource metadata at `https://app.getfinero.com/mcp/.well-known/oauth-protected-resource`. Access there is granted on a consent screen, where a person lets the agent act as them, and every call is checked against that person''s own permissions — not by OAuth scope values; the authorization server accepts only `openid`.'
externalDocs:
  description: Agent-facing orientation, including the MCP server and how to connect one.
  url: https://app.getfinero.com/llms.txt