Frihet Intelligence API

openapi: 3.2.0
info:
  title: Frihet Intelligence API
  version: '2026-03-18'
  description: 'The Frihet REST API provides programmatic access to your business data

    in Frihet, the AI-native business management platform for modern businesses. ## Authentication


    All API requests require an API key passed via the `X-API-Key` header. Generate keys from **Settings > API Keys** in the Frihet app. ```

    X-API-Key: fri_your_api_key_here

    ```


    ### API-key scopes


    A key without scopes (no list, or an empty one) is unrestricted. A key with a

    non-empty scope list gets only what the list grants. On such a key, every

    request other than `GET` and `HEAD` needs the `write` scope (or `*`), except

    the read-only `POST /v1/gestoria/aging` and the POS and purchase-order routes,

    which check their own `pos:` and `purchase-orders:` scopes. E-invoicing endpoints need an `einvoice:` scope,

    and the sends (`einvoice/export`, `face/submit`, `ticketbai/submit`) also need

    `write` or `einvoice:write`. A request without the scope it needs gets

    `403 Forbidden` with a `detail` naming that scope. The refusal happens before

    the idempotency gate, so it does not reserve the `Idempotency-Key`. `GET /v1/permissions/me` reports `denied.write`, `denied.einvoice` and

    `denied.einvoiceSend` for the calling key. Inventory (`/v1/inventory/*`) and purchase-order (`/v1/purchase-orders/*`) routes are

    not released yet: after the scope checks they answer `503` with code

    `INVENTORY_AUTHORITY_NOT_RELEASED`, before the idempotency gate. ## Rate Limiting


    The API enforces a rate limit of **100 requests per minute** per API key. When exceeded, the API returns `429 Too Many Requests` with an integer

    delta-seconds `Retry-After` header and matching `retryAfter` JSON field. Every authenticated response includes rate limit headers:


    | Header | Description |

    |--------|-------------|

    | `X-RateLimit-Limit` | Maximum requests per window (100) |

    | `X-RateLimit-Remaining` | Remaining requests in current window |

    | `X-RateLimit-Reset` | Unix timestamp (seconds) when the window resets |

    | `Retry-After` | Integer seconds until the window resets (429 responses) |


    ## Idempotency


    Most POST requests accept an `Idempotency-Key` header to prevent duplicate

    resource creation from network retries. For protected routes, the key is

    reserved against the operation *before* the request is executed, and it stays

    reserved for 24 hours unless released by an explicit pre-write refusal. ```

    Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

    ```


    Keys must be at most 64 characters. We recommend UUID v4. A retry of the same operation gets one of three answers:


    | Situation | Response |

    |---|---|

    | The first request finished | The **original status and body**, verbatim, with `X-Idempotent-Replayed: true` |

    | The first request is still running, or its outcome could not be recorded | `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` |

    | The key is live but was used for a **different** operation | `409 IDEMPOTENCY_KEY_REUSED` — the second operation is not executed |


    The replayed status is the **stored** one. A `201` replays as `201`, not `200`. This includes stored error responses: a request that answered `4xx` or `5xx`

    replays that same status and body, it does not re-execute — except explicit

    pre-mutation refusals on `POST /v1/pos/cash-sessions/{id}/close` (`503` when

    the workspace POS money-authority grant is not enabled and `403 POS_INACTIVE`

    before the POS app is activated), which release the reservation instead of

    caching the refusal for 24 hours. ### When a retry is refused


    A `409 IDEMPOTENCY_REQUEST_IN_PROGRESS` after the first request already

    returned means the outcome could not be recorded — the response was too large

    or unserializable, or the bookkeeping write failed. The API refuses rather than

    execute a second time, because for a fiscal document a duplicate is not

    recoverable. **Reconcile; do not simply retry with a fresh key.** Read the resource back

    (`GET` the collection, or look for the document the operation would have

    created) and decide from its actual state.'
  contact:
    name: Frihet API Support
    url: https://docs.frihet.io/desarrolladores/api-rest
    email: api@frihet.io
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-logo:
    url: https://frihet.io/logos/frihet-logo.svg
servers:
- url: https://api.frihet.io
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Intelligence
  description: AI-optimized endpoints providing business context, monthly P&L, and quarterly tax figures in a single call.
paths:
  /v1/context:
    get:
      operationId: getBusinessContext
      summary: Business context snapshot
      description: 'Returns a comprehensive business context snapshot in a single call,

        optimized for AI agents and MCP integrations. Includes business info,

        defaults, plan usage, invoice series, recent activity, top clients,

        and current month financials.'
      tags:
      - Intelligence
      responses:
        '200':
          description: Business context data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BusinessContext'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/monthly:
    get:
      operationId: getMonthlySummary
      summary: Monthly P&L
      description: 'Monthly financial summary with revenue breakdown (tax base, tax, IRPF),

        expense breakdown (deductible, tax), profit (gross/net), invoice status

        counts, top clients, expenses by category, and estimated tax liability

        (Modelo 303).'
      tags:
      - Intelligence
      parameters:
      - name: month
        in: query
        description: Month in YYYY-MM format. Defaults to current month.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}$
          example: 2026-03
      responses:
        '200':
          description: Monthly financial summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MonthlySummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/quarterly:
    get:
      operationId: getQuarterlySummary
      summary: Quarterly tax figures
      description: 'Quarterly tax preparation data including Modelo 303 (VAT) and

        Modelo 130 (quarterly income payment) pre-filled figures.

        Includes base imponible, cuotas, and estimated payments.

        Modelo 303 figures are returned only for a workspace that declares the

        peninsula fiscal zone with country ES; any other workspace gets a typed

        refusal in `modelo303` instead (no figures); the rest of the payload is

        unchanged.'
      tags:
      - Intelligence
      parameters:
      - name: quarter
        in: query
        description: Quarter in YYYY-Q1 format. Defaults to current quarter.
        schema:
          type: string
          pattern: ^\d{4}-Q[1-4]$
          example: 2026-Q1
      responses:
        '200':
          description: Quarterly tax summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuarterlySummary'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    RateLimited:
      description: Rate limit exceeded (100 requests per minute)
      headers:
        Retry-After:
          description: Integer seconds until the current rate-limit window resets
          schema:
            type: integer
            minimum: 1
          example: 60
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Rate limit exceeded
              message:
                type: string
                example: Maximum 100 requests per minute
              retryAfter:
                type: integer
                description: Seconds until rate limit resets
                example: 60
              meta:
                type: object
                properties:
                  requestId:
                    type: string
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Validation error
            details:
            - code: invalid_type
              message: Required
              path:
              - clientName
            meta:
              requestId: 550e8400-e29b-41d4-a716-446655440000
    Unauthorized:
      description: Authentication required or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid or expired API key
            meta:
              requestId: 550e8400-e29b-41d4-a716-446655440000
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error
            meta:
              requestId: 550e8400-e29b-41d4-a716-446655440000
  headers:
    X-RateLimit-Reset:
      description: Unix timestamp (seconds) when the rate limit window resets
      schema:
        type: integer
        example: 1742310060
  schemas:
    BusinessContext:
      type: object
      description: Comprehensive business context snapshot for AI agents
      properties:
        data:
          type: object
          properties:
            business:
              type: object
              properties:
                name:
                  type: string
                taxId:
                  type: string
                fiscalZone:
                  type: string
                currency:
                  type: string
                language:
                  type: string
                country:
                  type: string
            defaults:
              type: object
              properties:
                taxRate:
                  type: number
                irpfRate:
                  type: number
                dueDays:
                  type: integer
                currency:
                  type: string
            plan:
              type: object
              properties:
                name:
                  type: string
                  example: pro
                invoices:
                  type: object
                  properties:
                    used:
                      type: integer
                    limit:
                      type: integer
                expenses:
                  type: object
                  properties:
                    used:
                      type: integer
                    limit:
                      type: integer
                aiMessages:
                  type: object
                  properties:
                    used:
                      type: integer
                    limit:
                      type: integer
            series:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  prefix:
                    type: string
                  current:
                    type: integer
                  year:
                    type: integer
            recentActivity:
              type: object
              properties:
                lastInvoice:
                  type: object
                  nullable: true
                  properties:
                    number:
                      type: string
                    date:
                      type: string
                    client:
                      type: string
                lastExpense:
                  type: object
                  nullable: true
                  properties:
                    date:
                      type: string
                    vendor:
                      type: string
                    amount:
                      type: number
                overdueCount:
                  type: integer
                overdueAmount:
                  type: number
                unpaidCount:
                  type: integer
            topClients:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  totalRevenue:
                    type: number
                  invoiceCount:
                    type: integer
            currentMonth:
              type: object
              properties:
                revenue:
                  type: number
                expenses:
                  type: number
                profit:
                  type: number
                invoiceCount:
                  type: integer
                expenseCount:
                  type: integer
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Optional machine-readable code, including MISSING_FISCAL_INFO, AEAT_QR_UNAVAILABLE (422) and AEAT_RECORD_IRREPRODUCIBLE (409) on invoice PDF.
        message:
          type: string
          description: Optional explanatory message accompanying the error code.
        details:
          type: array
          description: Validation error details (Zod issues). Only present on 400 validation errors.
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
              path:
                type: array
                items:
                  type: string
        meta:
          type: object
          properties:
            requestId:
              type: string
              description: Unique request identifier for tracing
    MonthlySummary:
      type: object
      properties:
        data:
          type: object
          properties:
            period:
              type: string
              example: 2026-03
            revenue:
              type: object
              properties:
                total:
                  type: number
                taxBase:
                  type: number
                tax:
                  type: number
                irpf:
                  type: number
            expenses:
              type: object
              properties:
                total:
                  type: number
                deductible:
                  type: number
                tax:
                  type: number
            profit:
              type: object
              properties:
                gross:
                  type: number
                net:
                  type: number
            invoices:
              type: object
              properties:
                created:
                  type: integer
                sent:
                  type: integer
                paid:
                  type: integer
                overdue:
                  type: integer
            topClients:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  totalRevenue:
                    type: number
                  invoiceCount:
                    type: integer
            byCategory:
              type: object
              additionalProperties:
                type: number
              description: Expense totals grouped by category
            taxLiability:
              type: object
              properties:
                vatPayable:
                  type: number
                  description: Net VAT payable (output - input)
                irpfRetained:
                  type: number
                estimatedModel303:
                  type: number
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
    QuarterlySummary:
      type: object
      properties:
        data:
          type: object
          properties:
            period:
              type: string
              example: 2026-Q1
            months:
              type: array
              items:
                type: string
              example:
              - 2026-01
              - 2026-02
              - 2026-03
            modelo303:
              type: object
              description: 'Pre-filled Modelo 303 (IVA return) figures. Read-only summary, never submitted. Tax family per invoice = explicit taxType, otherwise the issuer workspace''s fiscal zone (peninsula = IVA, canarias = IGIC, ceuta_melilla = IPSI); the client''s location never decides it. Figures are returned only for a workspace that declares the peninsula fiscal zone with country ES, and whose fiscal-profile zone (if set) is peninsula too. Any other workspace gets a refusal here instead and NO figures: only `error`, `code` (MODELO_303_NOT_APPLICABLE), `reason`, `applicableModel` and, for zone_not_applicable, `fiscalZone`: the body of the 409 of GET /fiscal/modelo/303 without `meta`. The rest of the payload is unchanged.'
              properties:
                code:
                  type: string
                  enum:
                  - MODELO_303_NOT_APPLICABLE
                  description: Refusal only. Present instead of the figures below.
                reason:
                  type: string
                  enum:
                  - zone_undeclared
                  - zone_not_applicable
                  - zone_country_mismatch
                  description: Refusal only. zone_undeclared = no declared country and fiscal zone (or an unrecognised fiscal-profile zone); zone_not_applicable = the declared zone does not file Modelo 303; zone_country_mismatch = peninsula declared with a country other than ES.
                fiscalZone:
                  type: string
                  enum:
                  - canarias
                  - ceuta_melilla
                  - eu
                  - world
                  description: Refusal only, when reason is zone_not_applicable.
                applicableModel:
                  type: string
                  nullable: true
                  description: Refusal only. The IGIC return a Canary Islands workspace files instead ("420"); null otherwise.
                error:
                  type: string
                  description: Refusal only. Human-readable explanation.
                baseImponible:
                  type: number
                  description: Total tax base across all tax families (IVA, IGIC, IPSI, exempt)
                cuotaRepercutida:
                  type: number
                  description: Output IVA charged to clients (IGIC and IPSI excluded, see outOfScope)
                outOfScope:
                  type: object
                  description: IGIC (Canarias) and IPSI (Ceuta/Melilla) base and cuota kept out of the Modelo 303 figures. Informational; not part of the IVA return.
                  properties:
                    igic:
                      type: object
                      properties:
                        base:
                          type: number
                        cuota:
                          type: number
                    ipsi:
                      type: object
                      properties:
                        base:
                          type: number
                        cuota:
                          type: number
                baseDeducible:
                  type: number
                  description: Deductible expense base
                cuotaDeducible:
                  type: number
                  description: Input VAT (paid on deductible expenses)
                resultado:
                  type: number
                  description: Net VAT (output - input)
            modelo130:
              type: object
              description: Pre-filled Modelo 130 (IRPF pago fraccionado, estimación directa) figures. Read-only, never submitted. Per the AEAT instructions every figure is YEAR-TO-DATE (1 January to the last day of the requested quarter), not the quarter alone. Accrual basis (invoice issueDate, expense date); draft and cancelled invoices are excluded. Casillas 13-19 (minoraciones, vivienda habitual, complementaria) are not computed and are returned as null.
              properties:
                ingresos:
                  type: number
                  description: Casilla 01 — computable income, year-to-date
                gastos:
                  type: number
                  description: Casilla 02 — deductible expenses, year-to-date
                rendimientoNeto:
                  type: number
                  description: Casilla 03 — net income (ingresos - gastos), year-to-date, may be negative
                pagoFraccionado:
                  type: number
                  description: 'Casilla 12 — max(0, casilla 07): 20% of the positive year-to-date net income minus prior positive payments of the year and minus retenciones. Before the non-computed reductions of casillas 13-16.'
                retencionesSoportadas:
                  type: number
                  description: Casilla 06 — IRPF withheld on issued invoices, year-to-date
                basis:
                  type: string
                  enum:
                  - ytd
                year:
                  type: integer
                quarter:
                  type: integer
                  minimum: 1
                  maximum: 4
                porcentaje:
                  type: number
                  description: Percentage applied in casilla 04 (always 20; see notModelled)
                casillas:
                  type: object
                  description: Official AEAT casillas. Non-computed casillas are null.
                  properties:
                    c01:
                      type: number
                    c02:
                      type: number
                    c03:
                      type: number
                    c04:
                      type: number
                      description: 20% of the positive casilla 03, otherwise 0
                    c05:
                      type: number
                      description: Sum of the positive casilla 07 of earlier quarters of the same year, recomputed from stored documents
                    c06:
                      type: number
                    c07:
                      type: number
                      description: c04 - c05 - c06, may be negative
                    c12:
                      type: number
                      description: max(0, c07)
                    c13:
                      type: 'null'
                    c14:
                      type: 'null'
                    c15:
                      type: 'null'
                    c16:
                      type: 'null'
                    c17:
                      type: 'null'
                    c18:
                      type: 'null'
                    c19:
                      type: 'null'
                pagosAnterioresPorTrimestre:
                  type: array
                  description: Recomputed casilla 07 of each earlier quarter of the year (source of c05)
                  items:
                    type: object
                    properties:
                      quarter:
                        type: integer
                      c07:
                        type: number
                excluded:
                  type: object
                  description: Counted invoices / expenses skipped because their date is missing or not ISO YYYY-MM-DD
                  properties:
                    invoicesWithoutValidDate:
                      type: integer
                    expensesWithoutValidDate:
                      type: integer
                notModelled:
                  type: array
                  description: AEAT rules this summary does not apply
                  items:
                    type: string
                sourceUrl:
                  type: string
                  description: AEAT Modelo 130 instructions used as ground truth
            summary:
              type: object
              properties:
                totalRevenue:
                  type: number
                totalExpenses:
                  type: number
                invoiceCount:
                  type: integer
                clientCount:
                  type: integer
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key for authentication. Keys start with `fri_` prefix.

        Generate keys from Settings > API Keys in the Frihet app.

        '